@mieweb/pulsevault 0.4.2 → 0.6.0

package/dist/storage/types.d.ts

@@ -1,4 +1,5 @@
 import type { DataStore } from '@tus/server';
+import type { WebReadyResult } from '../lib/web-ready.js';
 /**
  * How the GET route should serve a resolved artifact. Stream means
  * `@fastify/send` reads directly from a local path; Redirect issues an HTTP
@@ -82,6 +83,112 @@ export type ReserveUploadParams = {
      * an operator can tell which app build produced a file. Display metadata only, like `name`.
      */
     appVersion?: string;
+    /**
+     * Opaque host data the capability token carried (`issueCapabilityToken`'s `context`: an owner,
+     * a destination), as the `authorize` hook returned it for this create. Persisted verbatim so
+     * every later hook, status read and completion replay gets it back without a host lookup.
+     * JSON only; never interpreted by PulseVault.
+     */
+    context?: unknown;
+};
+/** Everything an adapter knows about one artifact, from `describeArtifact`. */
+export type PulseVaultArtifactMeta = {
+    artifactId: string;
+    kind: UploadKind;
+    /**
+     * Lowercase extension of the stored file, including the leading dot: the uploaded file's,
+     * until a web-ready conversion turned another container into an MP4 (then `.mp4`).
+     */
+    ext: string;
+    /**
+     * The uploaded file's extension — `filename`'s, and the one tus's record of the upload is kept
+     * under — when a conversion stored the artifact under a different `ext`; absent otherwise. Use
+     * `uploadIdOf` to name the tus upload.
+     */
+    sourceExt?: string;
+    /** Original filename from `Upload-Metadata.filename`. */
+    filename: string;
+    relatedTo?: string;
+    checksum?: string;
+    name?: string;
+    appVersion?: string;
+    /** See `ReserveUploadParams.context`. */
+    context?: unknown;
+    /** `true` once the upload finished and is served. */
+    ready: boolean;
+    /**
+     * Whether the host's `onUploadComplete` has returned for this artifact: `false` from reserve,
+     * `true` once the core recorded the hook's return. A completion the host never recorded (a
+     * throw, a restart) is replayed from this flag. A sidecar written before the flag existed reads
+     * as `true` when finished (an upgrade replays nothing) and `false` while still uploading (its
+     * completion is still to come).
+     */
+    acknowledged: boolean;
+    /**
+     * Whether the web-ready conversion has finished for this artifact: `false` from reserve, `true`
+     * once the core recorded it. Only meaningful for a video on a server with `webReady`; the core
+     * derives the `processing` status from it. Legacy sidecars read as `true` when finished.
+     */
+    converted: boolean;
+    /** What the web-ready conversion did (`none`, `remuxed`, …, or `skipped` and why), once it ran. */
+    webReady?: WebReadyResult;
+    /** Whatever the host recorded with `recordOutcome` (where the upload went, why it was kept). */
+    outcome?: unknown;
+    /**
+     * A token for this reservation of the artifactId, new at every `reserveUpload`, so work that
+     * began on one upload can tell the id was removed and reserved again meanwhile (the
+     * `generation` patch condition). Required for `webReady` conversions: an adapter that offers
+     * `getLocalPath` but keeps no generation has its videos recorded `skipped`, never converted,
+     * since a queued conversion couldn't tell its upload from a later one of the same id. (The
+     * local adapter keeps one, and gives one at `markReady` to an upload reserved before it did.)
+     */
+    generation?: string;
+    /** Same meaning as `PulseVaultArtifactRecord.updatedAt`. */
+    updatedAt: number;
+    /**
+     * When the upload finished (ms since the epoch), recorded by `markReady` and never changed
+     * after — a stable order for "the newest related file", which `updatedAt` isn't (a later
+     * acknowledgement or outcome moves it). Absent on sidecars written before it was recorded.
+     */
+    readyAt?: number;
+};
+/**
+ * tus's id for an artifact's upload (`<kind>/<artifactId><ext>`), under the extension it was
+ * uploaded with — which a conversion to another container doesn't change.
+ */
+export declare function uploadIdOf(meta: Pick<PulseVaultArtifactMeta, 'kind' | 'artifactId' | 'ext' | 'sourceExt'>): string;
+/** The fields `patchArtifact` may change. Each is optional; absent means unchanged. */
+export type PulseVaultArtifactPatch = {
+    acknowledged?: boolean;
+    converted?: boolean;
+    /** What the web-ready conversion did. */
+    webReady?: WebReadyResult;
+    /**
+     * The stored file's new extension, after a web-ready conversion wrote the artifact's bytes
+     * under it (`<kind>/<artifactId><ext>`): from then on the artifact is served from that file.
+     * Only adapters that store files on local disk support it; others throw.
+     */
+    ext?: string;
+    /**
+     * Apply the patch only while `converted` is still false, so a conversion's record never
+     * replaces one another pass already made (two instances converting the same artifact).
+     */
+    unlessConverted?: boolean;
+    /**
+     * Apply the patch only to this reservation of the artifactId (`PulseVaultArtifactMeta
+     * .generation`; `null` for one without a generation), not to an upload that reserved the same
+     * id after it was removed.
+     */
+    generation?: string | null;
+    /**
+     * A file to install as the artifact's stored bytes, under the same lock as the rest of the
+     * patch: renamed onto `<kind>/<artifactId><ext>` (with `ext` the new one when it changes),
+     * after which a previous stored file under another extension is deleted. Must be in the
+     * artifact's kind directory. Only adapters that store files on local disk support it.
+     */
+    file?: string;
+    /** `null` clears a recorded outcome. */
+    outcome?: unknown;
 };
 /** One artifact as `listArtifacts` reports it. */
 export type PulseVaultArtifactRecord = {
@@ -176,5 +283,24 @@ export interface PulseVaultStorage {
     listArtifacts?(opts?: {
         changedBefore?: number;
     }): AsyncIterable<PulseVaultArtifactRecord>;
+    /**
+     * Everything stored about one artifact, or `null` if the artifactId is unknown. Optional —
+     * the richer hook context, `getStatus`, `getPulse`, reclaiming idle uploads and replaying
+     * completions all need it (both built-in adapters have it).
+     */
+    describeArtifact?(artifactId: string): Promise<PulseVaultArtifactMeta | null>;
+    /**
+     * Change the bookkeeping of one artifact (`acknowledged`, `converted`, `webReady`, `ext`,
+     * `outcome`, or its stored `file`). Resolves `false`, changing nothing, when the artifactId is
+     * unknown or a condition (`unlessConverted`, `generation`) doesn't hold. Optional —
+     * completion replay, background web-ready and `recordOutcome` need it.
+     */
+    patchArtifact?(artifactId: string, patch: PulseVaultArtifactPatch): Promise<boolean>;
+    /**
+     * The artifacts that declared `relatedTo` this one (a pulse's captions, beat manifest and
+     * thumbnail), in flight or finished. Optional — `getPulse` and the poster route need it. Built
+     * from an index the adapter keeps at reserve time, so it never scans every artifact.
+     */
+    listRelated?(artifactId: string): AsyncIterable<PulseVaultArtifactRecord>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/storage/types.d.ts.map

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

package/dist/storage/types.js

@@ -11,4 +11,11 @@ export function parseUploadKind(raw) {
     const lower = (raw ?? '').trim().toLowerCase();
     return UPLOAD_KINDS.includes(lower) ? lower : 'video';
 }
+/**
+ * tus's id for an artifact's upload (`<kind>/<artifactId><ext>`), under the extension it was
+ * uploaded with — which a conversion to another container doesn't change.
+ */
+export function uploadIdOf(meta) {
+    return `${meta.kind}/${meta.artifactId}${meta.sourceExt ?? meta.ext}`;
+}
 //# sourceMappingURL=types.js.map

package/dist/storage/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"AA4BA;;uCAEuC;AACvC,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,CAAU,CAAC;AAInF;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,GAA8B;IAC5D,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC/C,OAAQ,YAAkC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAE,KAAoB,CAAC,CAAC,CAAC,OAAO,CAAC;AAC/F,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"AA6BA;;uCAEuC;AACvC,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,CAAU,CAAC;AAInF;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,GAA8B;IAC5D,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC/C,OAAQ,YAAkC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAE,KAAoB,CAAC,CAAC,CAAC,OAAO,CAAC;AAC/F,CAAC;AA0HD;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,IAA+E;IACxG,OAAO,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;AACxE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mieweb/pulsevault",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "description": "Resumable video uploads via TUS for Fastify (plugin) or any Node backend (framework-agnostic core), with a pluggable storage adapter and a filesystem-first local-storage default.",
   "type": "module",
   "main": "./dist/app.js",
@@ -105,7 +105,7 @@
     "@tus/s3-store": "^2.0.6"
   },
   "pulseProtocol": {
-    "version": "2.2",
+    "version": "2.5",
     "min": 2,
     "max": 2
   }

package/protocol/openapi.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "Pulse upload protocol",
     "description": "The HTTP surface of the Pulse upload protocol, as implemented by @mieweb/pulsevault. Generated from the plugin's route schemas — see PROTOCOL.md for the full contract.",
-    "version": "2.2"
+    "version": "2.5"
   },
   "components": {
     "schemas": {}
@@ -1047,6 +1047,275 @@
           }
         }
       }
+    },
+    "/pulsevault/artifacts/{artifactId}/status": {
+      "get": {
+        "summary": "Where an upload is: uploading, processing or ready",
+        "tags": [
+          "pulsevault"
+        ],
+        "description": "Reports the artifact's state (`unknown`, `uploading`, `processing` while a web-ready conversion rewrites it, `ready`), its kind and `relatedTo`, the bytes received against its declared length, whether the host's `onUploadComplete` has finished (`acknowledged`), and what the host recorded with `recordOutcome` (`outcome`). Runs the `authorize` hook with `phase: \"status\"`; `createCapabilityAuthorize` grants it to the pairing token and to a view token. Never cached.",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "query",
+            "name": "token",
+            "required": false,
+            "description": "Optional bearer token (the pairing token or a view token), forwarded to the `authorize` hook as `ctx.token` for browsers that can’t set a header."
+          },
+          {
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            },
+            "in": "path",
+            "name": "artifactId",
+            "required": true,
+            "description": "UUID of the upload to report on."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Where an upload is (PROTOCOL.md §6.5, protocol 2.3; `webReady` 2.5): for a page waiting on it, so the host needs no table of its own. Authorized like opening the artifact. Never cached.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "title": "GET /artifacts/<id>/status response",
+                  "description": "Where an upload is (PROTOCOL.md §6.5, protocol 2.3; `webReady` 2.5): for a page waiting on it, so the host needs no table of its own. Authorized like opening the artifact. Never cached.",
+                  "type": "object",
+                  "required": [
+                    "artifactId",
+                    "state"
+                  ],
+                  "properties": {
+                    "artifactId": {
+                      "type": "string",
+                      "format": "uuid",
+                      "description": "The artifact asked about."
+                    },
+                    "state": {
+                      "type": "string",
+                      "enum": [
+                        "unknown",
+                        "uploading",
+                        "processing",
+                        "ready"
+                      ],
+                      "description": "`unknown` for an id the server has never seen; `uploading` until the final byte; `processing` while the server converts the bytes for the web; `ready` once the artifact is served."
+                    },
+                    "kind": {
+                      "type": "string",
+                      "enum": [
+                        "video",
+                        "project",
+                        "captions",
+                        "thumbnail"
+                      ],
+                      "description": "Artifact kind. Absent when `state` is `unknown`."
+                    },
+                    "relatedTo": {
+                      "type": "string",
+                      "format": "uuid",
+                      "description": "The video this artifact belongs to, if it declared one."
+                    },
+                    "name": {
+                      "type": "string",
+                      "description": "The display name the client sent (`Upload-Metadata.name`), if any."
+                    },
+                    "bytesReceived": {
+                      "type": "number",
+                      "description": "Bytes received so far while `uploading`, or stored once finished, when the server knows."
+                    },
+                    "size": {
+                      "type": "number",
+                      "description": "The upload's declared length, when the server knows."
+                    },
+                    "acknowledged": {
+                      "type": "boolean",
+                      "description": "Whether the host has finished handling the completed upload (its `onUploadComplete` returned)."
+                    },
+                    "webReady": {
+                      "type": "object",
+                      "required": [
+                        "action",
+                        "reason"
+                      ],
+                      "description": "What the server's web-ready conversion did, once it ran (protocol 2.5): `none` (already in the served format), `remuxed`, `transcoded`, `conformed` (another container became an MP4), or `skipped` (the original bytes serve) — with a reason a person can read. Absent until it has run, and on servers that don't convert.",
+                      "properties": {
+                        "action": {
+                          "type": "string",
+                          "enum": [
+                            "none",
+                            "remuxed",
+                            "transcoded",
+                            "conformed",
+                            "skipped"
+                          ]
+                        },
+                        "reason": {
+                          "type": "string"
+                        }
+                      }
+                    },
+                    "outcome": {
+                      "description": "What the host recorded about where the upload went, or why it didn't. Any JSON; absent until the host records one."
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "`artifactId` is not a valid UUID.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "description": "`artifactId` is not a valid UUID.",
+                  "type": "object",
+                  "properties": {
+                    "ok": {
+                      "type": "boolean"
+                    },
+                    "error": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "ok",
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authorize hook rejected the request.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "description": "Authorize hook rejected the request.",
+                  "type": "object",
+                  "properties": {
+                    "ok": {
+                      "type": "boolean"
+                    },
+                    "error": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "ok",
+                    "error"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/pulsevault/artifacts/{artifactId}/poster": {
+      "get": {
+        "summary": "Serve a video's poster frame",
+        "tags": [
+          "pulsevault"
+        ],
+        "description": "Streams or redirects to the finished thumbnail `relatedTo` the video, exactly as `GET /artifacts/:artifactId` would serve it. Runs the `authorize` hook with `phase: \"resolve\"` on the video, so whoever may watch it may see its poster. 404 until the poster has landed.",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "query",
+            "name": "token",
+            "required": false,
+            "description": "Optional bearer token for pre-authenticated watch links, forwarded to the `authorize` hook as `ctx.token`."
+          },
+          {
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            },
+            "in": "path",
+            "name": "artifactId",
+            "required": true,
+            "description": "UUID of the video (the pulse's anchor artifact)."
+          }
+        ],
+        "responses": {
+          "400": {
+            "description": "`artifactId` is not a valid UUID.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "description": "`artifactId` is not a valid UUID.",
+                  "type": "object",
+                  "properties": {
+                    "ok": {
+                      "type": "boolean"
+                    },
+                    "error": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "ok",
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authorize hook rejected the request.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "description": "Authorize hook rejected the request.",
+                  "type": "object",
+                  "properties": {
+                    "ok": {
+                      "type": "boolean"
+                    },
+                    "error": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "ok",
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "The video has no finished poster frame.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "description": "The video has no finished poster frame.",
+                  "type": "object",
+                  "properties": {
+                    "ok": {
+                      "type": "boolean"
+                    },
+                    "error": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "ok",
+                    "error"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
     }
   },
   "tags": [

package/protocol/schemas/artifact-status.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mieweb/pulsevault/blob/main/protocol/schemas/artifact-status.schema.json",
+  "title": "GET /artifacts/<id>/status response",
+  "description": "Where an upload is (PROTOCOL.md §6.5, protocol 2.3; `webReady` 2.5): for a page waiting on it, so the host needs no table of its own. Authorized like opening the artifact. Never cached.",
+  "type": "object",
+  "required": ["artifactId", "state"],
+  "properties": {
+    "artifactId": {
+      "type": "string",
+      "format": "uuid",
+      "description": "The artifact asked about."
+    },
+    "state": {
+      "type": "string",
+      "enum": ["unknown", "uploading", "processing", "ready"],
+      "description": "`unknown` for an id the server has never seen; `uploading` until the final byte; `processing` while the server converts the bytes for the web; `ready` once the artifact is served."
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["video", "project", "captions", "thumbnail"],
+      "description": "Artifact kind. Absent when `state` is `unknown`."
+    },
+    "relatedTo": {
+      "type": "string",
+      "format": "uuid",
+      "description": "The video this artifact belongs to, if it declared one."
+    },
+    "name": {
+      "type": "string",
+      "description": "The display name the client sent (`Upload-Metadata.name`), if any."
+    },
+    "bytesReceived": {
+      "type": "number",
+      "description": "Bytes received so far while `uploading`, or stored once finished, when the server knows."
+    },
+    "size": {
+      "type": "number",
+      "description": "The upload's declared length, when the server knows."
+    },
+    "acknowledged": {
+      "type": "boolean",
+      "description": "Whether the host has finished handling the completed upload (its `onUploadComplete` returned)."
+    },
+    "webReady": {
+      "type": "object",
+      "required": ["action", "reason"],
+      "description": "What the server's web-ready conversion did, once it ran (protocol 2.5): `none` (already in the served format), `remuxed`, `transcoded`, `conformed` (another container became an MP4), or `skipped` (the original bytes serve) — with a reason a person can read. Absent until it has run, and on servers that don't convert.",
+      "properties": {
+        "action": {
+          "type": "string",
+          "enum": ["none", "remuxed", "transcoded", "conformed", "skipped"]
+        },
+        "reason": { "type": "string" }
+      }
+    },
+    "outcome": {
+      "description": "What the host recorded about where the upload went, or why it didn't. Any JSON; absent until the host records one."
+    }
+  }
+}

package/protocol/schemas/capability-token.schema.json

@@ -31,6 +31,9 @@
       "type": "string",
       "enum": ["view"],
       "description": "`view` on a read-only view token (§5.5), which only opens artifacts and is signed with a key derived from the secret. Absent on the capability token an upload uses."
+    },
+    "ctx": {
+      "description": "Opaque host data signed into the token (protocol 2.3): who the upload is for, where it goes. The server stores it with the artifact the token creates and hands it back to its own hooks; a client never reads it. Any JSON, at most 1 KiB encoded."
     }
   }
 }

package/protocol/schemas/deep-link.schema.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/mieweb/pulsevault/blob/main/protocol/schemas/deep-link.schema.json",
-  "title": "Pairing link query parameters",
-  "description": "The query parameters of a `pulsecam://?…` pairing link (PROTOCOL.md §3), as built by `buildUploadLink`. Clients must ignore parameters they don't recognize.",
+  "title": "Pairing link parameters",
+  "description": "The parameters of a pairing link (PROTOCOL.md §3), as built by `buildUploadLink`: the query string of `pulsecam://?…`, or the fragment of `https://mieweb.github.io/pulse/open#…`. Clients must ignore parameters they don't recognize.",
   "type": "object",
   "required": ["v", "artifactId", "server"],
   "properties": {

package/scripts/web-ready-migrate.mjs

@@ -1,17 +1,20 @@
 #!/usr/bin/env node
-// Make every already-uploaded video artifact in a local-storage workspace
-// web-playable, in place. New uploads are handled by the `onUploadComplete`
-// web-ready hook (see examples/fastify-demo/server.mjs); this script is the
-// one-time backfill for artifacts that landed before the hook existed.
+// Conform every already-uploaded video artifact in a local-storage workspace
+// to the format PulseVault serves (`CONFORM_TARGET`). New uploads are handled
+// by the `webReady` option; this script is the one-time backfill for
+// artifacts that landed before it was on. Stop the server first: it caches
+// each artifact's extension, which a container change rewrites.
 //
 // For each ready `kind: "video"` sidecar in `<workspaceDir>/.pulsevault/`:
-//   - moov atom at the end of the file  → lossless faststart remux (sub-second)
-//   - non-H.264 video codec (e.g. HEVC) → one-time libx264 transcode
-//   - already web-ready / not MP4 bytes → untouched
+//   - already in the target format          → untouched
+//   - moov atom at the end of an MP4        → lossless faststart remux
+//   - off-target video or audio             → one ffmpeg run (H.264/AAC, scaled, tone-mapped)
+//   - another container (WebM, MKV, MOV, …) → a new `<id>.mp4`; the sidecar
+//     switches to it and the original is deleted
 //
 // Rewrites are atomic (tmp file + rename), so interrupting the script never
 // corrupts an artifact — rerun it and it picks up where it left off (already
-// fixed files report `none` and are skipped for free).
+// fixed files report `none`).
 //
 // Usage:
 //   node scripts/web-ready-migrate.mjs <workspaceDir> [--dry-run] [--no-transcode]
@@ -46,7 +49,7 @@ try {
   process.exit(1);
 }
 
-const counts = { none: 0, remuxed: 0, transcoded: 0, skipped: 0, missing: 0 };
+const counts = { none: 0, remuxed: 0, transcoded: 0, conformed: 0, skipped: 0, missing: 0 };
 let processed = 0;
 
 for (const sidecarFile of sidecarFiles) {
@@ -84,8 +87,29 @@ for (const sidecarFile of sidecarFiles) {
     continue;
   }
 
-  const result = await ensureWebReady(filePath, { transcode, logger: console });
+  const { outputPath, ...result } = await ensureWebReady(filePath, { transcode, logger: console });
   counts[result.action] += 1;
+  // Record what was done on the sidecar, as the server does; a new container also switches the
+  // artifact to its `.mp4` (keeping the uploaded extension as `sourceExt`), then the original
+  // goes. Atomic tmp + rename, like the adapter's own sidecar writes.
+  // A rerun finds a converted file already in the format: keep what the conversion recorded,
+  // and finish what an interrupted run left: the original, once the sidecar names the `.mp4`.
+  if (result.action === "none" && sidecar.webReady) {
+    if (sidecar.sourceExt && sidecar.sourceExt !== sidecar.ext) {
+      await fs.rm(path.join(root, kind, `${artifactId}${sidecar.sourceExt}`), { force: true });
+    }
+    continue;
+  }
+  const next = { ...sidecar, converted: true, webReady: result };
+  if (outputPath) {
+    next.sourceExt = sidecar.sourceExt ?? sidecar.ext;
+    next.ext = path.extname(outputPath);
+  }
+  const sidecarPath = path.join(sidecarDir, sidecarFile);
+  const tmpPath = `${sidecarPath}.migrate.tmp`;
+  await fs.writeFile(tmpPath, JSON.stringify(next), "utf8");
+  await fs.rename(tmpPath, sidecarPath);
+  if (outputPath) await fs.rm(filePath, { force: true });
   if (result.action !== "none") {
     console.log(`${result.action.padEnd(11)}  ${artifactId}  (${result.reason})`);
   }
@@ -96,7 +120,7 @@ if (dryRun) {
 } else {
   console.log(
     `\nDone: ${processed} ready video artifact(s) — ` +
-      `${counts.remuxed} remuxed, ${counts.transcoded} transcoded, ` +
+      `${counts.remuxed} remuxed, ${counts.transcoded} transcoded, ${counts.conformed} conformed, ` +
       `${counts.none} already web-ready, ${counts.skipped} skipped, ${counts.missing} missing.`,
   );
 }