@mieweb/pulsevault 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -47,6 +47,23 @@ if you've evaluated against an intermediate build.
   requirement on server implementations generally, not just this package).
 - Both are covered by new regression tests in `test/plugin.test.mjs` that
   fail against the pre-fix code and pass against the fix.
+- **Removed `s3rver`** (unmaintained) from the dev/test toolchain, clearing
+  its open `npm audit` findings: its dependency chain carried high-severity
+  advisories (`busboy`/`dicer`) and forced pinning `fast-xml-parser` via an
+  `overrides` entry plus a hand-written API-compat shim. The S3 suite now runs
+  against `test/mock-s3.mjs`, a zero-dependency in-memory S3 double
+  implementing exactly the eleven operations the code under test uses. Unlike
+  s3rver it enforces `If-None-Match: "*"` (412), so the adapter's atomic
+  reserve collision guard is now genuinely exercised — a concurrent-reserve
+  test that was impossible against s3rver has been added. The `ListParts` shim
+  (s3rver never implemented it) is gone too.
+- **5xx responses no longer echo internal error messages.** A `markReady`,
+  `onUploadComplete`, or 5xx-class `validatePayload` failure now logs the real
+  error server-side and returns a generic body, so a consumer's DB/storage error
+  text (schema names, paths, infra detail) can't reach the uploading client. 4xx
+  validation rejections (e.g. checksum mismatch) keep their descriptive messages.
+- **Storage subdirectories are created with mode `0o750`** so the upload tree
+  isn't world-readable under a permissive umask.
 
 ### Breaking
 
@@ -77,12 +94,24 @@ if you've evaluated against an intermediate build.
 
 ### Added
 
-- **`kind: "captions"`** artifact type (default extension `.srt`), running
+- **`name`** — an optional `Upload-Metadata` key carrying a free-form UTF-8
+  display title for the artifact (e.g. the draft name typed on the capture
+  device). Trimmed and hard-capped server-side (512 chars), persisted to the
+  sidecar alongside `relatedTo`/`checksum`, and exposed via the new optional
+  `getName` storage method (and `ReserveUploadParams.name`). Display-only
+  metadata: it never influences storage paths, routing, or authorization, and
+  consumers must escape it for their own output context. Optional everywhere,
+  so older clients that don't send it and consumers that don't read it are
+  unaffected. Documented in `PROTOCOL.md` §4.1 as a non-normative extension.
+- **`kind: "captions"`** artifact type (default extension `.vtt`), running
   through the same generic `validatePayload`/`onUploadComplete` hooks as
-  every other kind.
+  every other kind. WebVTT carries word-level inline cue timestamps
+  (`<00:00:01.500>word`) for karaoke rendering, and both storage adapters
+  serve `.vtt` artifacts with the `text/vtt` content type.
 - **`relatedTo`** — an optional `Upload-Metadata` key (and matching
   `ReserveUploadParams`/storage field) linking one artifact to another (e.g.
-  a video's captions, or a beat belonging to a pulse manifest's session).
+  a merged video's captions/beat-manifest/thumbnail, or a clip belonging to a
+  segment ordering manifest's session).
   Storage adapters expose it via the new optional `getRelatedTo` method.
 - **`checksum`** — an optional `Upload-Metadata` key (`<algorithm>:<hex
   digest>`) verified post-upload via the new `createChecksumValidator`
@@ -102,14 +131,21 @@ if you've evaluated against an intermediate build.
   `uploadUnit`, `kinds`, `allowedExtensions`, `maxUploadSize`, and supported
   checksum algorithms. Lets independently-versioned deployments and clients
   detect compatibility before pairing.
-- **`uploadUnit` plugin option** (`"beat" | "merged"`, default `"beat"`) —
+- **`uploadUnit` plugin option** (`"segment" | "merged"`, default `"segment"`) —
   purely advertised via `/capabilities`; the operator declares which upload
   strategy this deployment expects, the client branches on it. Not enforced
-  by the plugin.
+  by the plugin. `"segment"` uploads each recorded clip plus an ordering
+  manifest; `"merged"` uploads one pre-merged video plus its captions, a
+  beat-timecode manifest, and a thumbnail. (A "beat" is a timecode range on
+  the merged timeline, not an upload unit.)
+- **`kind: "thumbnail"`** artifact type (default extensions `.jpg`/`.jpeg`/
+  `.png`) — the pulse poster frame uploaded alongside a merged video, running
+  through the same generic `validatePayload`/`onUploadComplete` hooks and a
+  `thumbnail/` storage subdir like every other kind.
 - **`buildUploadLink({ uploadUnit })`** (PROTOCOL.md §3, §8) — optional
   per-session override of the deployment-wide `uploadUnit`, carried on the
   pairing link itself instead of only `/capabilities`. Lets an operator run
-  `"beat"` and `"merged"` sessions concurrently (staged rollout, A/B test,
+  `"segment"` and `"merged"` sessions concurrently (staged rollout, A/B test,
   per-tenant policy) without racing a client's separate `/capabilities` fetch
   against a single, deployment-wide value. Fully backward compatible: omit it
   and a client falls back to `/capabilities` exactly as before.
@@ -144,8 +180,55 @@ if you've evaluated against an intermediate build.
   counterpart to `readAll`, now used internally by
   `createS3ChecksumValidator` (see "Fixed" below).
 
+### Changed
+
+- Replaced `examples/rn-demo` with two focused Fastify examples:
+  `examples/fastify-demo` (the smallest runnable server — no auth, local
+  storage, QR pairing; start here) and `examples/fastify-auth-demo`
+  (production-shaped reference — capability tokens always on, failing fast at
+  boot without `PULSEVAULT_SECRET`, pulse-session grouping via `relatedTo`,
+  WebVTT captions, Swagger UI, artifact-event feed). Both pairing pages
+  are React (pinned ESM CDN builds, no bundler). Both examples are
+  local-storage only; S3 wiring is documented in the README's S3 section
+  rather than demonstrated in an example. `npm run e2e` now drives
+  `fastify-auth-demo` and additionally asserts the fail-fast boot contract.
+- `examples/fastify-auth-demo` gained a [Better Auth](https://better-auth.com)
+  dashboard layer: the human-facing routes (`/deeplinks`, `/pulses`,
+  `/events`, `/reserve`) require an email+password session, while the vault
+  routes the Pulse app talks to stay capability-token authorized — two auth
+  systems for two audiences, per PROTOCOL.md §5. The demo is Postgres-only,
+  run through Docker Compose (`compose.yaml` + `Dockerfile`; `npm run db:up`
+  + `npm start` for bare-metal dev against the same db), with one Prisma
+  schema (`prisma/schema.prisma`, migrations committed and applied by
+  `npm start`) holding both the auth tables and an **artifact index**:
+  `onUploadComplete` writes each finished upload once, authorized deletes
+  prune it, a boot-time reconcile keeps it honest against the filesystem
+  sidecars (still the source of truth), and `/pulses` becomes one indexed
+  query instead of a per-request sidecar crawl. `npm run e2e` provisions the
+  compose db, applies migrations, and covers the 401 gate plus the
+  sign-up/sign-in flow.
+
 ### Fixed
 
+- **Artifact `GET`/`DELETE` handlers now fail closed.** They run on a hijacked
+  socket, so a thrown storage error (S3 unreachable, disk fault) previously left
+  the socket hung until timeout; each now emits a `500` (or destroys the socket
+  if headers are already sent), mirroring the TUS handler. `GET` streams also
+  catch a mid-stream read error instead of letting an unhandled `'error'` crash
+  the process, and destroy the source stream on client disconnect so file
+  descriptors aren't leaked. Covered by `test/fail-closed.test.mjs`.
+- A consumer error carrying an out-of-range `statusCode` (e.g. `42`) now degrades
+  to the handler's fallback status instead of crashing `res.writeHead`; a
+  malformed request-target that `URL` can't parse returns `400` instead of an
+  uncaught throw.
+- Checksum verification requested against an adapter with no local path now
+  reports `500` (server misconfiguration) instead of `422` (which wrongly
+  implied the client's file was rejected).
+- `verifyCapabilityToken` no longer throws on a token whose payload is valid
+  JSON but not an object (e.g. the literal `null`) — it returns `null` like
+  every other failure, per its single-failure-shape contract.
+- Bearer-token extraction accepts the auth scheme case-insensitively per
+  RFC 7235 (`bearer`/`BEARER`), not only the canonical `Bearer `.
 - `maxUploadSize` enforcement and the in-progress-upload 404 behavior now
   have explicit test coverage proving bytes are rejected/hidden at the right
   point, not just implied by the implementation.
@@ -175,8 +258,8 @@ if you've evaluated against an intermediate build.
 - **Silent TOCTOU on S3-compatible backends without `IfNoneMatch` support.**
   `reserveUpload`'s conditional-write collision guard falls back to a
   weaker check-then-write on backends that reject `IfNoneMatch` (some
-  S3-compatible stores, and the `s3rver` mock this repo's own test suite
-  runs against) — this reopens the race between concurrent/retried creates
+  S3-compatible stores) — this reopens the race between concurrent/retried
+  creates
   for the same artifactId. There's no way to close it without an external
   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.

package/OPERATIONS.md

@@ -66,8 +66,8 @@ you have a specific reason to use local disk.
 `reserveUpload`'s collision guard normally uses `PutObjectCommand`'s
 `IfNoneMatch: "*"` to atomically reject a second create for an artifactId
 that already has an upload. Some S3-compatible backends (older/less-complete
-implementations; the `s3rver` mock this package's own test suite runs
-against) don't support conditional writes and reject that header outright.
+implementations) don't support conditional writes and reject that header
+outright.
 On those backends, `reserveUpload` falls back to a weaker check-then-write —
 functionally the same guard, but with the original race reopened: two
 truly concurrent (or retried) creates for the same artifactId can both pass
@@ -153,8 +153,8 @@ upload routes.
 ## Backup and restore (local storage)
 
 The entire state of the local adapter lives under `workspaceDir`:
-`.pulsevault/` (sidecars), `video/`, `project/`, `captions/` (bytes). Back it
-up as a normal filesystem tree — there's no separate database to keep in
+`.pulsevault/` (sidecars), `video/`, `project/`, `captions/`, `thumbnail/`
+(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

package/PROTOCOL.md

@@ -37,9 +37,9 @@ The response body MUST be a JSON object with at least the following fields:
   "protocolVersion": 1,
   "minSupportedVersion": 1,
   "maxSupportedVersion": 1,
-  "uploadUnit": "beat",
-  "kinds": ["video", "project", "captions"],
-  "allowedExtensions": { "video": [".mp4"], "project": [".pulse", ".zip"], "captions": [".srt"] },
+  "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"] }
 }
@@ -52,9 +52,10 @@ The response body MUST be a JSON object with at least the following fields:
   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` (`"beat"` or `"merged"`, REQUIRED): which upload strategy this
+- `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.
+  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.
@@ -74,7 +75,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=<beat|merged>
+pulsecam://?v=1&artifactId=<uuid>&server=<origin>&token=<opaque>&uploadUnit=<segment|merged>
 ```
 
 - `v` (REQUIRED): the deep-link schema version. A client MUST refuse and
@@ -96,14 +97,14 @@ pulsecam://?v=1&artifactId=<uuid>&server=<origin>&token=<opaque>&uploadUnit=<bea
   `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, `"beat"` or `"merged"`): per-session override of the
+- `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 "beat" and
+  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.
@@ -138,9 +139,15 @@ pairs) MUST be parsed for at least:
 |---|---|---|
 | `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`, or `captions`. |
+| `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. |
+
+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
+Latin-1 string (e.g. a browser `btoa()`) corrupts any non-ASCII title (accents,
+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
@@ -239,8 +246,9 @@ 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 video, its captions, and every beat + manifest
-under `uploadUnit: "beat"`) rather than requiring one token per artifact.
+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.
 
 This shape is exactly what `@mieweb/pulsevault`'s `issueCapabilityToken`/
 `verifyCapabilityToken`/`createCapabilityAuthorize` implement, but any server
@@ -282,22 +290,53 @@ clear, specific message rather than a generic failure.
 
 ## 8. Artifact relationships (`relatedTo`) and `uploadUnit`
 
-A pulse (a short composed of one or more beats) MAY be uploaded as a single
-pre-merged video (`uploadUnit: "merged"`) or as individual per-beat artifacts
-plus a manifest (`uploadUnit: "beat"`) — 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.
-
-Under `uploadUnit: "beat"`, a client uploads each beat under its own
-`artifactId`, plus one manifest artifact (`kind: "project"`, a JSON document
-listing the ordered beat `artifactId`s) and, optionally, per-beat captions
-(`kind: "captions"`). Every non-primary artifact in the 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).
-
-The relational graph of replies between beats/pulses (who replied to what,
+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.
+
+```json
+{ "version": 1, "segments": [ { "artifactId": "<uuid>", "order": 0 } ] }
+```
+
+Under `uploadUnit: "merged"`, a client uploads one pre-merged video as the
+session anchor, plus (all as 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
+  `<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 **thumbnail** (`kind: "thumbnail"`, `<draftId>.jpg`) — the pulse's poster
+  frame.
+
+```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).
+
+The relational graph of replies between segments/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

package/README.md

@@ -173,14 +173,28 @@ diagnostics — the Fastify plugin always uses `request.log` for these
 automatically, but a non-Fastify host has no equivalent to infer one from,
 so it falls back to `console` when omitted.
 
-See [`examples/express-demo`](examples/express-demo) and
-[`examples/meteor-demo`](examples/meteor-demo) for full runnable servers
-(pairing page, QR codes, auth demo, local/S3 storage) — the Express and
-Meteor counterparts to [`examples/rn-demo`](examples/rn-demo)'s Fastify
-demo, both built on `@mieweb/pulsevault/core` instead of the plugin. 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.
+Four runnable example servers live under [`examples/`](examples):
+
+- [`examples/fastify-demo`](examples/fastify-demo) — the smallest runnable
+  server: Fastify plugin mount, QR pairing, flat upload listing, no auth,
+  local storage. Start here.
+- [`examples/fastify-auth-demo`](examples/fastify-auth-demo) —
+  production-shaped Fastify reference, run through Docker Compose (server +
+  Postgres, one `docker compose up --build`): capability tokens always on
+  (fails fast at boot without `PULSEVAULT_SECRET`), a [Better
+  Auth](https://better-auth.com)-protected React dashboard (email+password),
+  a Prisma schema holding both the auth tables and an artifact index
+  (`onUploadComplete` writes each finished upload once; `/pulses` is one
+  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.
 
 ## How a pairing + upload session flows
 
@@ -229,12 +243,12 @@ type PulseVaultPluginOptions = {
   storage: PulseVaultStorage;
   prefix: string;
   maxUploadSize: number;
-  uploadUnit?: "beat" | "merged";              // default: "beat" — see "Upload unit"
+  uploadUnit?: "segment" | "merged";           // default: "segment" — see "Upload unit"
   decoratorName?: string;                      // default: "pulseVault"
   allowedExtensions?:
-    | string[]                                                          // legacy — treated as video-only
-    | { video?: string[]; project?: string[]; captions?: string[] };    // per-kind (recommended)
-  // defaults: { video: [".mp4"], project: [".pulse", ".zip"], captions: [".srt"] }
+    | 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"] }
   cache?: PulseVaultCacheOptions;
   authorize?: PulseVaultAuthorize;
   validatePayload?: PulseVaultValidatePayload;          // runs for every kind; branch on ctx.kind
@@ -263,12 +277,14 @@ Maximum upload size in bytes. Use `Infinity` for no cap.
 
 ### Upload unit
 
-`uploadUnit: "beat" | "merged"` — purely advertised via `GET /pulsevault/capabilities`; **the plugin doesn't enforce either.** It tells the client which upload strategy this deployment expects:
+`uploadUnit: "segment" | "merged"` — purely advertised via `GET /pulsevault/capabilities`; **the plugin doesn't enforce either.** It tells the client which upload strategy this deployment expects:
 
-- `"beat"` (default): the client uploads each clip individually (no merge/re-encode pass), plus a `kind=project` manifest artifact for ordering. Lower client-side cost, finer-grained resumability.
-- `"merged"`: the client pre-merges a pulse's clips into one video before uploading. Simpler server-side mental model (one artifact per pulse), more client-side work.
+- `"segment"` (default): the client uploads each recorded clip individually (no merge/re-encode pass), plus one `kind=project` ordering manifest (`<draftId>-segments.pulse`). No captions or thumbnail. Lower client-side cost, finer-grained resumability.
+- `"merged"`: the client pre-merges a pulse's clips into one video before uploading, alongside its captions (`kind=captions`), a beat-timecode manifest (`kind=project`, `<draftId>-beats.pulse` — per-segment `startMs`/`endMs` on the merged timeline), and a poster `kind=thumbnail`. Simpler server-side mental model (one primary artifact per pulse), more client-side work.
 
-A client reads this at pairing time, before doing any merge or upload work, and branches accordingly. See `PROTOCOL.md` §8 for the full contract.
+(A "beat" is a timecode range on the merged timeline — one recorded segment's placement within the merged video — not an upload unit. The old `"beat"` upload unit was renamed to `"segment"`.)
+
+A client reads `uploadUnit` at pairing time, before doing any merge or upload work, and branches accordingly. See `PROTOCOL.md` §8 for the full contract.
 
 Need both strategies live at once instead of one fixed value for the whole deployment? Pass `uploadUnit` to [`buildUploadLink`](#deep-link-helper) per session — it overrides `/capabilities` for that pairing only, with no server-side option to change.
 
@@ -288,13 +304,13 @@ File extensions accepted per artifact kind. Three accepted forms:
 
 ```ts
 // 1. Omit entirely — uses all three defaults:
-//    video: [".mp4"]   project: [".pulse", ".zip"]   captions: [".srt"]
+//    video: [".mp4"]   project: [".pulse", ".zip"]   captions: [".vtt"]
 
 // 2. Flat array (legacy) — video-only; project/captions keep their defaults:
 allowedExtensions: [".mp4"]
 
 // 3. Per-kind object — unset keys fall back to their defaults:
-allowedExtensions: { video: [".mp4"], project: [".pulse"], captions: [".srt"] }
+allowedExtensions: { video: [".mp4"], project: [".pulse"], captions: [".vtt"] }
 ```
 
 All extensions must include the leading dot and are matched case-insensitively. The `kind` field in `Upload-Metadata` determines which list is checked.
@@ -457,9 +473,9 @@ When the final PATCH lands the plugin runs the following steps in order, for eve
   "protocolVersion": 1,
   "minSupportedVersion": 1,
   "maxSupportedVersion": 1,
-  "uploadUnit": "beat",
-  "kinds": ["video", "project", "captions"],
-  "allowedExtensions": { "video": [".mp4"], "project": [".pulse", ".zip"], "captions": [".srt"] },
+  "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"] }
 }
@@ -506,7 +522,7 @@ 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 video also covers its captions and (under `uploadUnit: "beat"`) every beat and the manifest 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 merged video also covers its captions, beat manifest and thumbnail (or, under `uploadUnit: "segment"`, every clip and the ordering manifest) 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.
 
 ## Upload-Metadata protocol
 
@@ -520,11 +536,14 @@ The TUS `Upload-Metadata` header is a comma-separated list of `<key> <base64>` p
 | `kind` | No | `video` (default), `project`, or `captions`. Determines the storage subdir and which hooks fire. |
 | `relatedTo` | No | UUID of another artifact this one belongs to (e.g. a video's captions). Lets one capability token authorize a whole session. |
 | `checksum` | No | `<algorithm>:<hex digest>` of the finished file, verified by `createChecksumValidator`/`createS3ChecksumValidator` if configured. |
+| `name` | No | Free-form UTF-8 display title (e.g. the draft name typed on the capture device). Trimmed + length-capped, persisted to the sidecar, and readable via `storage.getName(artifactId)`. Display-only — never used for storage paths or authorization; escape it for your output context. |
+
+> Base64 the **UTF-8 bytes** of each value. `filename`/`kind`/`artifactId` are ASCII, but a free-form `name` can carry accents or emoji — a browser `btoa()` (Latin-1) corrupts those, so encode via `Buffer`/`TextEncoder` (or your platform's UTF-8-safe base64) for the `name` value.
 
 Example (`kind=captions`, linked to a video):
 
 ```
-Upload-Metadata: artifactId <base64(uuid)>, filename <base64("clip.srt")>, kind <base64("captions")>, relatedTo <base64(videoArtifactId)>
+Upload-Metadata: artifactId <base64(uuid)>, filename <base64("clip.vtt")>, kind <base64("captions")>, relatedTo <base64(videoArtifactId)>
 ```
 
 ## Local storage
@@ -544,7 +563,7 @@ The local adapter writes uploads into flat kind-scoped subdirectories. Downstrea
 
 ```text
 <workspaceRoot>/
-  .pulsevault/<id>.json           # sidecar: { version, ext, filename, status, kind, relatedTo, checksum }
+  .pulsevault/<id>.json           # sidecar: { version, ext, filename, status, kind, relatedTo, checksum, name }
   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")
@@ -555,7 +574,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)` and `storage.getChecksum(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.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.
 
 **Horizontal scaling**: this adapter requires sticky-session routing or a shared filesystem across instances — see `OPERATIONS.md`.
 
@@ -640,14 +659,14 @@ Credentials are optional — omit `accessKeyId`/`secretAccessKey` to use the AWS
 
 ```text
 <bucket>/
-  .pulsevault/<id>.json   # metadata sidecar: { version, ext, filename, status, kind, relatedTo, checksum }
+  .pulsevault/<id>.json   # metadata sidecar: { version, ext, filename, status, kind, relatedTo, checksum, name }
   video/<id><ext>         # finalized video object    (kind="video")
   project/<id><ext>       # finalized project object  (kind="project")
   captions/<id><ext>      # finalized captions object (kind="captions")
   <key>.info              # @tus/s3-store multipart bookkeeping (transient)
 ```
 
-`resolve()` only returns a presigned URL once the sidecar `status` is `"ready"` (after the final byte lands and `validatePayload` passes), so in-progress or rejected uploads are never served. `getKind(id)` returns the kind without a full resolve; `getRelatedTo(id)`/`getChecksum(id)` mirror the local adapter.
+`resolve()` only returns a presigned URL once the sidecar `status` is `"ready"` (after the final byte lands and `validatePayload` passes), so in-progress or rejected uploads are never served. `getKind(id)` returns the kind without a full resolve; `getRelatedTo(id)`/`getChecksum(id)`/`getName(id)` mirror the local adapter.
 
 ### Options
 
@@ -664,7 +683,7 @@ Credentials are optional — omit `accessKeyId`/`secretAccessKey` to use the AWS
 | `metaCacheLimit` | `10000` | Caps the in-memory metadata cache before evicting the oldest entry. |
 | `clientConfig` | — | Advanced: extra `S3ClientConfig` merged into the client. |
 
-> The runnable demo wires these to environment variables — see [`examples/rn-demo/.env.example`](examples/rn-demo/.env.example) for the full list (`STORAGE`, `S3_BUCKET`, `S3_ENDPOINT`, `AWS_REGION`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, …).
+> A typical deployment wires these to environment variables (e.g. `S3_BUCKET`, `S3_ENDPOINT`, `AWS_REGION`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`) and picks the storage adapter with a `STORAGE=local|s3` switch — the options table above maps one-to-one onto `createS3Storage(...)`.
 
 ### Payload validation on remote storage
 
@@ -692,9 +711,9 @@ const storage: PulseVaultStorage = {
   async shutdown() {
     /* optional teardown */
   },
-  async reserveUpload({ artifactId, filename, ext, kind, relatedTo, checksum }) {
+  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, status: "uploading" });
+    await db.createArtifact({ artifactId, filename, kind, relatedTo, checksum, name, status: "uploading" });
     return `${kind}/${artifactId}${ext}`;
   },
   async resolve(artifactId): Promise<PulseVaultResolution | null> {
@@ -718,10 +737,12 @@ const storage: PulseVaultStorage = {
     const result = await db.deleteArtifact(artifactId);
     return result.deleted;
   },
-  // Optional — only needed if you use relatedTo/checksum-aware hooks/validators:
+  // Optional — relatedTo/checksum-aware hooks/validators, plus getName so a
+  // display title is available via storage.getName:
   async getKind(artifactId) { return (await db.findArtifact(artifactId))?.kind ?? null; },
   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; },
 };
 ```
 
@@ -745,7 +766,7 @@ const uploadLink = buildUploadLink({
 // pulsecam://?v=1&artifactId=...&server=https%3A%2F%2Fexample.com%2Fpulsevault&token=secret&uploadUnit=merged
 ```
 
-`uploadUnit` on the link is a **per-session override** of whatever `GET /capabilities` currently reports (PROTOCOL.md §3, §8). Omit it and nothing changes — the client falls back to `/capabilities` exactly as before. Set it when you want "beat" and "merged" sessions live at the same time (staged rollout, A/B test, per-tenant policy) instead of one fixed value for the whole deployment — `/capabilities` can only ever report one current value, and a client reading it separately from opening the link is racing whatever the server happened to be serving at that moment, not the value this specific session was paired under.
+`uploadUnit` on the link is a **per-session override** of whatever `GET /capabilities` currently reports (PROTOCOL.md §3, §8). Omit it and nothing changes — the client falls back to `/capabilities` exactly as before. Set it when you want "segment" and "merged" sessions live at the same time (staged rollout, A/B test, per-tenant policy) instead of one fixed value for the whole deployment — `/capabilities` can only ever report one current value, and a client reading it separately from opening the link is racing whatever the server happened to be serving at that moment, not the value this specific session was paired under.
 
 ## Tests
 
@@ -763,14 +784,14 @@ Runs a Node `--test` suite against the built plugin. Coverage includes:
 - `kind=project` and `kind=captions` happy paths — correct subdir, `Content-Type`, sidecar, `relatedTo` linking
 - Extension mismatch rejections in both directions
 - `artifactId`/`videoid`/`projectid` metadata aliases
-- `getKind()`/`getRelatedTo()`/`getChecksum()` storage methods
+- `getKind()`/`getRelatedTo()`/`getChecksum()`/`getName()` storage methods
 - Legacy sidecars (no `kind` field) default to `"video"`, readable through the new generic route with no data migration
 - Sidecar corruption recovery
 - `allowedExtensions` object form
 - `createChecksumValidator`/`createS3ChecksumValidator`: matching digest accepted, mismatch rejected with cleanup
 - `issueCapabilityToken`/`verifyCapabilityToken`/`createCapabilityAuthorize`: round-trip, tampered signature/payload, expiry + clock tolerance, unknown `kid`, issuer mismatch, key-rotation overlap, `relatedTo`-based session authorization — both as fast unit tests (no server) and wired into real HTTP requests
 - `GET /capabilities`
-- S3/R2 backend (`createS3Storage`): full resumable upload → presigned-redirect playback, `createS3Mp4Sniffer`, `createS3ChecksumValidator`, `DELETE`, `kind=project`/`captions`, run against an in-process [s3rver](https://github.com/jamhall/s3rver) mock (no cloud credentials needed)
+- S3/R2 backend (`createS3Storage`): full resumable upload → presigned-redirect playback, `createS3Mp4Sniffer`, `createS3ChecksumValidator`, `DELETE`, `kind=project`/`captions`, run against an in-process zero-dependency S3 mock (`test/mock-s3.mjs`, no cloud credentials needed)
 - `@mieweb/pulsevault/core` (the framework-agnostic entry point): the same protocol suite re-run against a bare `http.createServer` wrapping `core.handler`, plus an Express-specific smoke test proving `app.use(prefix, handler)` composition
 
 ## Accessing storage outside the plugin routes

package/dist/app.d.ts

@@ -40,13 +40,14 @@ export type PulseVaultPluginOptions = {
      */
     maxUploadSize: number;
     /**
-     * Which upload strategy this deployment expects: `"beat"` uploads each
+     * Which upload strategy this deployment expects: `"segment"` uploads each
      * clip individually (no client-side merge/re-encode pass) plus a manifest
      * artifact for ordering, while `"merged"` expects one pre-merged video per
-     * pulse. Purely advertised via `GET /capabilities` for the client to branch
-     * on — `pulsevault` doesn't enforce either. Defaults to `"beat"`.
+     * pulse (plus its captions, beat manifest and thumbnail). Purely advertised
+     * via `GET /capabilities` for the client to branch on — `pulsevault` doesn't
+     * enforce either. Defaults to `"segment"`.
      */
-    uploadUnit?: 'beat' | 'merged';
+    uploadUnit?: 'segment' | 'merged';
     /**
      * Fastify instance decorator name under which the storage adapter is
      * exposed. Defaults to `"pulseVault"`. Override when registering this

package/dist/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}

package/dist/app.js

@@ -22,7 +22,7 @@ const app = async (fastify, opts) => {
         prefix: opts.prefix,
         storage: opts.storage,
         maxUploadSize: opts.maxUploadSize,
-        uploadUnit: opts.uploadUnit ?? 'beat',
+        uploadUnit: opts.uploadUnit ?? 'segment',
         allowedExtensions,
         cache: opts.cache,
         authorize: opts.authorize,

package/dist/app.js.map

@@ -1 +1 @@
-{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAChC,OAAO,gBAAgB,EAAE,EAA4B,MAAM,wBAAwB,CAAC;AAIpF,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,yBAAyB,EACzB,iCAAiC,EACjC,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,kBAAkB,CAAC;AAoJ1B,MAAM,sBAAsB,GAAG,YAAY,CAAC;AAE5C,MAAM,GAAG,GAAgD,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE;IAC/E,gBAAgB,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACxC,qBAAqB,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC1C,kBAAkB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACpC,yBAAyB,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAClD,iCAAiC,CAAC,IAAI,CAAC,CAAC;IAExC,2EAA2E;IAC3E,wEAAwE;IACxE,+BAA+B;IAC/B,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;QACpC,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;IAClC,CAAC,CAAC,CAAC;IACH,MAAM,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;IAElC,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,sBAAsB,CAAC;IACnE,MAAM,iBAAiB,GAAG,0BAA0B,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAE7E,OAAO,CAAC,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAE9C,MAAM,OAAO,CAAC,QAAQ,CAAC,gBAAgB,EAAE;QACvC,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,MAAM;QACrC,iBAAiB;QACjB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,eAAe,EAAE,sBAAsB,CAAC,IAAI,CAAC,eAAe,EAAE,IAAI,CAAC,sBAAsB,CAAC;QAC1F,gBAAgB,EAAE,uBAAuB,CAAC,IAAI,CAAC,gBAAgB,EAAE,IAAI,CAAC,uBAAuB,CAAC;QAC9F,eAAe,EAAE,IAAI,CAAC,eAAe;KACtC,CAAC,CAAC;AACL,CAAC,CAAC;AAEF,eAAe,EAAE,CAAC,GAAG,EAAE;IACrB,IAAI,EAAE,YAAY;IAClB,OAAO,EAAE,KAAK;CACf,CAAC,CAAC;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAkBlD,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEhF,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC;AAOnC,OAAO,EACL,uBAAuB,EACvB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAChC,OAAO,gBAAgB,EAAE,EAA4B,MAAM,wBAAwB,CAAC;AAIpF,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,yBAAyB,EACzB,iCAAiC,EACjC,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,kBAAkB,CAAC;AAqJ1B,MAAM,sBAAsB,GAAG,YAAY,CAAC;AAE5C,MAAM,GAAG,GAAgD,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE;IAC/E,gBAAgB,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACxC,qBAAqB,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC1C,kBAAkB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACpC,yBAAyB,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAClD,iCAAiC,CAAC,IAAI,CAAC,CAAC;IAExC,2EAA2E;IAC3E,wEAAwE;IACxE,+BAA+B;IAC/B,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;QACpC,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;IAClC,CAAC,CAAC,CAAC;IACH,MAAM,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;IAElC,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,sBAAsB,CAAC;IACnE,MAAM,iBAAiB,GAAG,0BAA0B,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAE7E,OAAO,CAAC,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAE9C,MAAM,OAAO,CAAC,QAAQ,CAAC,gBAAgB,EAAE;QACvC,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,SAAS;QACxC,iBAAiB;QACjB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,eAAe,EAAE,sBAAsB,CAAC,IAAI,CAAC,eAAe,EAAE,IAAI,CAAC,sBAAsB,CAAC;QAC1F,gBAAgB,EAAE,uBAAuB,CAAC,IAAI,CAAC,gBAAgB,EAAE,IAAI,CAAC,uBAAuB,CAAC;QAC9F,eAAe,EAAE,IAAI,CAAC,eAAe;KACtC,CAAC,CAAC;AACL,CAAC,CAAC;AAEF,eAAe,EAAE,CAAC,GAAG,EAAE;IACrB,IAAI,EAAE,YAAY;IAClB,OAAO,EAAE,KAAK;CACf,CAAC,CAAC;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAkBlD,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEhF,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC;AAOnC,OAAO,EACL,uBAAuB,EACvB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC"}

package/dist/core.d.ts

@@ -38,8 +38,8 @@ export type PulseVaultCoreOptions = {
     stripBasePath?: boolean;
     /** Max TUS upload size in bytes. Required — consumers must choose an explicit cap. Use `Infinity` for no cap. */
     maxUploadSize: number;
-    /** Which upload strategy this deployment expects. Purely advertised via `GET /capabilities`. Defaults to `"beat"`. */
-    uploadUnit?: 'beat' | 'merged';
+    /** Which upload strategy this deployment expects. Purely advertised via `GET /capabilities`. Defaults to `"segment"`. */
+    uploadUnit?: 'segment' | 'merged';
     /** File extensions allowed per artifact kind. See the Fastify plugin's `allowedExtensions` for the full shape. */
     allowedExtensions?: PulseVaultAllowedExtensionsInput;
     /** Cache-control options forwarded to `@fastify/send` for the GET route. */