@mieweb/pulsevault 0.4.2 → 0.6.0

package/dist/storage/local.js

@@ -1,11 +1,21 @@
 import { FileStore } from '@tus/file-store';
+import { ERRORS, Upload } from '@tus/server';
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { randomUUID } from 'node:crypto';
 import { isUuid } from '../lib/uuid.js';
+import { EXTENSION_REGEX } from '../lib/options.js';
+import { CONFORM_TARGET } from '../lib/web-ready.js';
 import { parseUploadKind } from './types.js';
 const SIDECAR_VERSION = 1;
 /** Hidden directory inside workspaceRoot that holds per-upload sidecar files. */
 const PULSEVAULT_META_DIR = '.pulsevault';
+/**
+ * Relation index under the metadata directory: `related/<anchorId>/<artifactId>` is an empty
+ * marker for every artifact that declared `relatedTo` the anchor, so a pulse's files are one
+ * `readdir` away instead of a scan of every sidecar.
+ */
+const RELATED_DIR = 'related';
 /** Default cap on the in-memory metadata cache before evicting the oldest entry. */
 const DEFAULT_META_CACHE_LIMIT = 10_000;
 /** Map a file extension to the `Content-Type` the GET route should return. */
@@ -17,6 +27,23 @@ function extToContentType(ext) {
             return 'application/zip';
         case '.vtt':
             return 'text/vtt';
+        case '.mov':
+            return 'video/quicktime';
+        case '.m4v':
+            return 'video/x-m4v';
+        case '.webm':
+            return 'video/webm';
+        case '.mkv':
+            return 'video/x-matroska';
+        case '.3gp':
+            return 'video/3gpp';
+        case '.avi':
+            return 'video/x-msvideo';
+        case '.srt':
+            return 'application/x-subrip';
+        case '.pulse':
+            // The beat manifest (PROTOCOL.md §8) is JSON.
+            return 'application/json';
         case '.jpg':
         case '.jpeg':
             return 'image/jpeg';
@@ -30,6 +57,7 @@ function extToContentType(ext) {
 function sidecarToCachedMeta(sidecar, ready) {
     return {
         ext: sidecar.ext,
+        ...(sidecar.sourceExt ? { sourceExt: sidecar.sourceExt } : {}),
         ready,
         kind: sidecar.kind ?? 'video',
         relatedTo: sidecar.relatedTo,
@@ -37,9 +65,71 @@ function sidecarToCachedMeta(sidecar, ready) {
         name: sidecar.name,
     };
 }
+/** A recorded web-ready result read back from a sidecar. */
+function isWebReadyResult(value) {
+    const result = value;
+    return (typeof result === 'object' &&
+        result !== null &&
+        typeof result.action === 'string' &&
+        typeof result.reason === 'string');
+}
 export function createLocalStorage(opts) {
     const workspaceRoot = path.resolve(opts.workspaceDir);
-    const datastore = new FileStore({ directory: workspaceRoot });
+    /**
+     * Whether the tus upload `uploadId` (`<kind>/<artifactId><ext>`) finished and a conversion then
+     * replaced its file: the sidecar is ready, names this upload's extension as `sourceExt`, and the
+     * file is gone. tus still has its record of the upload (`<uploadId>.json`).
+     */
+    const replacedByConversion = async (uploadId) => {
+        const slash = uploadId.indexOf('/');
+        const kind = uploadId.slice(0, slash);
+        const artifactId = uploadId.slice(slash + 1, slash + 37);
+        const ext = uploadId.slice(slash + 37);
+        if (slash < 0 || !isUuid(artifactId) || !EXTENSION_REGEX.test(ext))
+            return false;
+        const sidecar = await readSidecar(artifactId);
+        if (!sidecar || sidecar.status !== 'ready' || (sidecar.kind ?? 'video') !== kind)
+            return false;
+        if (sidecar.sourceExt !== ext || sidecar.ext === ext)
+            return false;
+        return (await storedExt(artifactId, sidecar.kind ?? 'video', ext)) !== ext;
+    };
+    /**
+     * tus's store for the workspace, which also answers for an upload a conversion replaced (a
+     * finished `.webm` conformed to `<id>.mp4`): tus would answer a client re-sending the final
+     * `PATCH` whose response it lost with `410`, the file being gone. Such an upload reads as
+     * complete, and its (empty) tail is taken without a write, so the retry reaches
+     * `onUploadFinish`'s already-finished branch and gets `204`, as one without a conversion does.
+     */
+    class LocalFileStore extends FileStore {
+        async getUpload(id) {
+            try {
+                return await super.getUpload(id);
+            }
+            catch (err) {
+                if (err !== ERRORS.FILE_NO_LONGER_EXISTS || !(await replacedByConversion(id)))
+                    throw err;
+                const record = await this.configstore.get(id);
+                if (!record || typeof record.size !== 'number')
+                    throw err;
+                return new Upload({
+                    id,
+                    size: record.size,
+                    offset: record.size,
+                    metadata: record.metadata,
+                    creation_date: record.creation_date,
+                });
+            }
+        }
+        async write(readable, id, offset) {
+            if (!(await replacedByConversion(id)))
+                return super.write(readable, id, offset);
+            for await (const _ of readable)
+                ; // a finished upload: nothing more to store
+            return offset;
+        }
+    }
+    const datastore = new LocalFileStore({ directory: workspaceRoot });
     const metaCacheLimit = opts.metaCacheLimit ?? DEFAULT_META_CACHE_LIMIT;
     // Metadata cache keyed by artifactId. Populated eagerly on reserve and
     // lazily from the sidecar on cache-miss — so we never do a workspace-wide
@@ -80,14 +170,78 @@ export function createLocalStorage(opts) {
     };
     /** Relative path (from workspaceRoot) to the artifact bytes. */
     const artifactRelPath = (artifactId, kind, ext) => `${kind}/${artifactId}${ext}`;
+    /** The artifact's bytes file, strictly inside its kind directory, as `sidecarPath` checks. */
+    const storedPath = (artifactId, kind, ext) => {
+        const base = path.resolve(workspaceRoot, kind);
+        const resolved = path.resolve(base, `${artifactId}${ext}`);
+        if (!resolved.startsWith(`${base}${path.sep}`)) {
+            throw new Error('artifactId escapes the kind directory');
+        }
+        return resolved;
+    };
+    /**
+     * The extension of the file that holds an artifact's bytes, given the `ext` its sidecar names:
+     * that file, or for a video the conform target (`<id>.mp4`) when only that exists. A sidecar
+     * another instance wrote from a copy older than a conversion still names the uploaded file,
+     * which the conversion deleted; its bytes are in the converted file. `null` when neither exists.
+     */
+    const storedExt = async (artifactId, kind, ext) => {
+        // Only a real id becomes a path, as everywhere else in this adapter.
+        if (!isUuid(artifactId) || !EXTENSION_REGEX.test(ext))
+            return null;
+        const candidates = kind === 'video' && ext !== CONFORM_TARGET.extension ? [ext, CONFORM_TARGET.extension] : [ext];
+        for (const candidate of candidates) {
+            try {
+                const stat = await fs.stat(storedPath(artifactId, kind, candidate));
+                if (stat.isFile())
+                    return candidate;
+            }
+            catch (err) {
+                if (err?.code !== 'ENOENT')
+                    throw err;
+            }
+        }
+        return null;
+    };
     const writeSidecar = async (artifactId, sidecar) => {
         // Atomic tmp + rename so a crash mid-write can never leave a truncated
-        // JSON blob that `loadMeta` would then treat as corrupt.
+        // JSON blob that `loadMeta` would then treat as corrupt. The tmp name is
+        // unique, so two writers (two instances on a shared filesystem) never
+        // write into, or rename away, each other's tmp file.
         const finalPath = sidecarPath(artifactId);
-        const tmpPath = `${finalPath}.tmp`;
+        const tmpPath = `${finalPath}.${randomUUID()}.tmp`;
         await fs.mkdir(sidecarDir(), { recursive: true, mode: 0o750 });
-        await fs.writeFile(tmpPath, JSON.stringify(sidecar), 'utf8');
-        await fs.rename(tmpPath, finalPath);
+        try {
+            await fs.writeFile(tmpPath, JSON.stringify(sidecar), 'utf8');
+            await fs.rename(tmpPath, finalPath);
+        }
+        catch (err) {
+            await fs.rm(tmpPath, { force: true });
+            throw err;
+        }
+    };
+    /**
+     * Read-modify-write of a sidecar runs one at a time per artifact in this process, so an
+     * acknowledgement, a conversion switching the stored file and a removal each act on the sidecar
+     * as the last of them left it. Across instances sharing the workspace (OPERATIONS.md,
+     * "Horizontal scaling") there is no lock: the last rename wins. The completion bookkeeping
+     * recovers: the replay redoes a lost acknowledgement or conversion record, idempotently, and a
+     * sidecar written from a copy older than a conversion still finds the bytes: a conversion's file
+     * is always `<id>.mp4`, which `resolve` and `getLocalPath` fall back to (`storedExt`). A lost
+     * `outcome` isn't redone; nothing records it a second time.
+     */
+    const sidecarWrites = new Map();
+    const withSidecarLock = async (artifactId, work) => {
+        const previous = sidecarWrites.get(artifactId) ?? Promise.resolve();
+        const run = previous.catch(() => { }).then(work);
+        sidecarWrites.set(artifactId, run);
+        try {
+            return await run;
+        }
+        finally {
+            if (sidecarWrites.get(artifactId) === run)
+                sidecarWrites.delete(artifactId);
+        }
     };
     const readSidecar = async (artifactId) => {
         // Every sidecar/artifact path in this module is built by joining
@@ -126,6 +280,9 @@ export function createLocalStorage(opts) {
             return {
                 version: SIDECAR_VERSION,
                 ext: parsed.ext,
+                ...(typeof parsed.sourceExt === 'string' && EXTENSION_REGEX.test(parsed.sourceExt)
+                    ? { sourceExt: parsed.sourceExt }
+                    : {}),
                 filename: parsed.filename,
                 status,
                 kind,
@@ -133,6 +290,15 @@ export function createLocalStorage(opts) {
                 checksum: typeof parsed.checksum === 'string' ? parsed.checksum : undefined,
                 name: typeof parsed.name === 'string' ? parsed.name : undefined,
                 appVersion: typeof parsed.appVersion === 'string' ? parsed.appVersion : undefined,
+                ...(parsed.context !== undefined ? { context: parsed.context } : {}),
+                // A sidecar from before the flag existed: finished means nothing to replay; still
+                // uploading means its completion hasn't happened yet.
+                acknowledged: parsed.acknowledged ?? status === 'ready',
+                converted: parsed.converted ?? status === 'ready',
+                ...(isWebReadyResult(parsed.webReady) ? { webReady: parsed.webReady } : {}),
+                ...(typeof parsed.generation === 'string' ? { generation: parsed.generation } : {}),
+                ...(parsed.outcome !== undefined ? { outcome: parsed.outcome } : {}),
+                ...(typeof parsed.readyAt === 'number' ? { readyAt: parsed.readyAt } : {}),
             };
         }
         catch {
@@ -141,6 +307,52 @@ export function createLocalStorage(opts) {
             return null;
         }
     };
+    /** Directory of relation markers for one anchor artifact. */
+    const relatedDir = (anchorId) => {
+        const base = path.resolve(sidecarDir(), RELATED_DIR);
+        const resolved = path.resolve(base, anchorId);
+        if (!resolved.startsWith(`${base}${path.sep}`)) {
+            throw new Error('artifactId escapes the metadata directory');
+        }
+        return resolved;
+    };
+    /** When the upload last moved: the sidecar's mtime, or the bytes file's while still uploading. */
+    const lastActivity = async (artifactId, sidecar) => {
+        let updatedAt;
+        try {
+            updatedAt = (await fs.stat(sidecarPath(artifactId))).mtimeMs;
+        }
+        catch {
+            return 0;
+        }
+        if (sidecar.status === 'uploading') {
+            const kind = sidecar.kind ?? 'video';
+            const bytes = path.join(workspaceRoot, kind, `${artifactId}${sidecar.ext}`);
+            const written = await fs.stat(bytes).then((stats) => stats.mtimeMs, () => 0);
+            updatedAt = Math.max(updatedAt, written);
+        }
+        return updatedAt;
+    };
+    const sidecarToMeta = (artifactId, sidecar, updatedAt) => ({
+        artifactId,
+        kind: sidecar.kind ?? 'video',
+        ext: sidecar.ext,
+        ...(sidecar.sourceExt ? { sourceExt: sidecar.sourceExt } : {}),
+        filename: sidecar.filename,
+        ...(sidecar.relatedTo ? { relatedTo: sidecar.relatedTo } : {}),
+        ...(sidecar.checksum ? { checksum: sidecar.checksum } : {}),
+        ...(sidecar.name ? { name: sidecar.name } : {}),
+        ...(sidecar.appVersion ? { appVersion: sidecar.appVersion } : {}),
+        ...(sidecar.context !== undefined ? { context: sidecar.context } : {}),
+        ready: sidecar.status === 'ready',
+        acknowledged: sidecar.acknowledged !== false,
+        converted: sidecar.converted !== false,
+        ...(sidecar.webReady ? { webReady: sidecar.webReady } : {}),
+        ...(sidecar.generation ? { generation: sidecar.generation } : {}),
+        ...(sidecar.outcome !== undefined ? { outcome: sidecar.outcome } : {}),
+        updatedAt,
+        ...(sidecar.readyAt !== undefined ? { readyAt: sidecar.readyAt } : {}),
+    });
     const loadMeta = async (artifactId) => {
         const cached = metaCache.get(artifactId);
         if (cached)
@@ -161,7 +373,7 @@ export function createLocalStorage(opts) {
         // tighten it so the upload tree isn't world-writable under a permissive umask.
         await fs.chmod(workspaceRoot, 0o750).catch(() => { });
     };
-    const reserveUpload = async ({ artifactId, filename, ext, kind, relatedTo, checksum, name, appVersion, }) => {
+    const reserveUpload = async ({ artifactId, filename, ext, kind, relatedTo, checksum, name, appVersion, context, }) => {
         await fs.mkdir(path.join(workspaceRoot, kind), { recursive: true, mode: 0o750 });
         await fs.mkdir(sidecarDir(), { recursive: true, mode: 0o750 });
         const sidecar = {
@@ -174,61 +386,75 @@ export function createLocalStorage(opts) {
             checksum,
             name,
             appVersion,
+            ...(context !== undefined ? { context } : {}),
+            acknowledged: false,
+            converted: false,
+            generation: randomUUID(),
         };
-        // Collision guard: `wx` fails atomically with EEXIST if a sidecar already exists for
-        // this artifactId, rather than the previous read-then-write (`loadMeta` then
-        // `writeSidecar`) which left a window for two concurrent/retried requests to both pass
-        // the check before either had written — letting the second silently clobber the first's
-        // sidecar and race @tus/file-store's own offset tracking. Translates to HTTP 409 via
-        // @tus/server's error path, same as before.
-        try {
-            await fs.writeFile(sidecarPath(artifactId), JSON.stringify(sidecar), { flag: 'wx' });
-        }
-        catch (err) {
-            if (err?.code !== 'EEXIST')
-                throw err;
-            // A file already exists at this path, but `readSidecar` treats a malformed/corrupt
-            // one as absent (e.g. debris from a crash mid-write) — re-check before deciding this
-            // is a genuine collision rather than debris that's safe to overwrite.
-            const existing = await readSidecar(artifactId);
-            if (existing) {
-                throw Object.assign(new Error(`artifactId ${artifactId} already has an upload`), {
-                    statusCode: 409,
-                    status_code: 409,
-                });
+        // Under the sidecar lock, so a removal of the same id in this process either finished
+        // (its sidecar went last) or hasn't started.
+        await withSidecarLock(artifactId, async () => {
+            // Collision guard: `wx` fails atomically with EEXIST if a sidecar already exists for
+            // this artifactId, rather than the previous read-then-write (`loadMeta` then
+            // `writeSidecar`) which left a window for two concurrent/retried requests to both pass
+            // the check before either had written — letting the second silently clobber the first's
+            // sidecar and race @tus/file-store's own offset tracking. Translates to HTTP 409 via
+            // @tus/server's error path, same as before.
+            try {
+                await fs.writeFile(sidecarPath(artifactId), JSON.stringify(sidecar), { flag: 'wx' });
             }
-            await writeSidecar(artifactId, sidecar);
+            catch (err) {
+                if (err?.code !== 'EEXIST')
+                    throw err;
+                // A file already exists at this path, but `readSidecar` treats a malformed/corrupt
+                // one as absent (e.g. debris from a crash mid-write) — re-check before deciding this
+                // is a genuine collision rather than debris that's safe to overwrite.
+                const existing = await readSidecar(artifactId);
+                if (existing) {
+                    throw Object.assign(new Error(`artifactId ${artifactId} already has an upload`), {
+                        statusCode: 409,
+                        status_code: 409,
+                    });
+                }
+                await writeSidecar(artifactId, sidecar);
+            }
+        });
+        if (relatedTo) {
+            // The relation index entry. Written after the sidecar so a crash between the two leaves
+            // an artifact without an index entry (it still works, it's just not listed under its
+            // anchor), never an index entry without an artifact.
+            const dir = relatedDir(relatedTo);
+            await fs.mkdir(dir, { recursive: true, mode: 0o750 });
+            await fs.writeFile(path.join(dir, artifactId), '', { flag: 'w' });
         }
         cacheSet(artifactId, { ext, ready: false, kind, relatedTo, checksum, name });
         // @tus/file-store joins this onto its configured `directory`, so the
         // actual file lands at `<workspaceRoot>/<kind>/<artifactId><ext>`.
         return artifactRelPath(artifactId, kind, ext);
     };
-    const resolve = async (artifactId) => {
+    const resolve = async (artifactId, reread = false) => {
         const meta = await loadMeta(artifactId);
         // Only serve ready uploads. In-progress uploads stay hidden — a client
         // GETting mid-upload would otherwise receive a truncated file.
         if (!meta || !meta.ready)
             return null;
-        const relFile = artifactRelPath(artifactId, meta.kind, meta.ext);
-        try {
-            const stat = await fs.stat(path.join(workspaceRoot, relFile));
-            if (!stat.isFile())
-                return null;
-        }
-        catch (err) {
-            if (err?.code === 'ENOENT')
+        const ext = await storedExt(artifactId, meta.kind, meta.ext);
+        if (ext === null) {
+            // The cache may be older than another instance's removal and new upload of the id: read
+            // the sidecar once more.
+            if (reread)
                 return null;
-            throw err;
+            metaCache.delete(artifactId);
+            return resolve(artifactId, true);
         }
         return {
             kind: 'stream',
             root: workspaceRoot,
-            filename: relFile,
-            contentType: extToContentType(meta.ext),
+            filename: artifactRelPath(artifactId, meta.kind, ext),
+            contentType: extToContentType(ext),
         };
     };
-    const markReady = async (artifactId) => {
+    const markReady = (artifactId) => withSidecarLock(artifactId, async () => {
         const sidecar = await readSidecar(artifactId);
         if (!sidecar) {
             // No sidecar means no `reserveUpload` happened for this artifactId —
@@ -240,29 +466,72 @@ export function createLocalStorage(opts) {
             cacheSet(artifactId, sidecarToCachedMeta(sidecar, true));
             return;
         }
-        await writeSidecar(artifactId, { ...sidecar, status: 'ready' });
+        // An upload reserved before generations were kept gets one now, so its conversion runs.
+        await writeSidecar(artifactId, {
+            ...sidecar,
+            status: 'ready',
+            readyAt: Date.now(),
+            generation: sidecar.generation ?? randomUUID(),
+        });
         cacheSet(artifactId, sidecarToCachedMeta(sidecar, true));
-    };
-    const remove = async (artifactId) => {
-        const meta = await loadMeta(artifactId);
+    });
+    // Under the sidecar lock, from the sidecar itself: in this process, a conversion switching the
+    // artifact to a new file (`patchArtifact` with `ext`) either finishes first — and this removes
+    // the new file — or finds the sidecar gone and drops what it wrote.
+    const remove = (artifactId) => withSidecarLock(artifactId, async () => {
+        // The sidecar decides, never the cache: a read racing this removal (or an earlier one) can
+        // have cached the artifact again, and a removal that trusted it would report the same
+        // artifact removed twice.
+        const sidecar = await readSidecar(artifactId);
         // Drop from cache before rm so a racing `resolve` arriving after the
         // rm but before cache eviction can't hand back a stale path.
         metaCache.delete(artifactId);
-        if (!meta)
+        if (!sidecar)
             return false;
+        const meta = sidecarToCachedMeta(sidecar, sidecar.status === 'ready');
         const artifactPath = path.join(workspaceRoot, meta.kind, `${artifactId}${meta.ext}`);
+        // The uploaded file and tus's record of it, when a conversion stored the bytes under a new
+        // extension (normally already gone; left behind by a crash during the switch).
+        const sourcePath = meta.sourceExt
+            ? path.join(workspaceRoot, meta.kind, `${artifactId}${meta.sourceExt}`)
+            : null;
+        // A video's conversion output, whatever this sidecar's copy says (`storedExt`).
+        const conformedPath = meta.kind === 'video' && meta.ext !== CONFORM_TARGET.extension
+            ? path.join(workspaceRoot, artifactRelPath(artifactId, meta.kind, CONFORM_TARGET.extension))
+            : null;
         await Promise.all([
             fs.rm(artifactPath, { force: true }),
             fs.rm(`${artifactPath}.json`, { force: true }),
-            fs.rm(sidecarPath(artifactId), { force: true }),
+            ...(sourcePath
+                ? [fs.rm(sourcePath, { force: true }), fs.rm(`${sourcePath}.json`, { force: true })]
+                : []),
+            ...(conformedPath ? [fs.rm(conformedPath, { force: true })] : []),
+            ...(meta.relatedTo
+                ? [fs.rm(path.join(relatedDir(meta.relatedTo), artifactId), { force: true })]
+                : []),
         ]);
+        // Last: until the sidecar is gone the id can't be reserved again, so a new upload of it
+        // never has its bytes removed by this one's removal.
+        await fs.rm(sidecarPath(artifactId), { force: true });
+        // Again: a read during the removal may have cached it from the sidecar it still saw.
+        metaCache.delete(artifactId);
         return true;
-    };
+    });
+    /**
+     * From the sidecar, not the cache: another instance on the same workspace may have removed
+     * the artifact and reserved its id again (a new extension) since this one cached it, and a
+     * caller about to read or rewrite the bytes must get today's file.
+     */
     const getLocalPath = async (artifactId) => {
-        const meta = await loadMeta(artifactId);
-        if (!meta)
+        const sidecar = await readSidecar(artifactId);
+        if (!sidecar) {
+            metaCache.delete(artifactId);
             return null;
-        return path.join(workspaceRoot, meta.kind, `${artifactId}${meta.ext}`);
+        }
+        cacheSet(artifactId, sidecarToCachedMeta(sidecar, sidecar.status === 'ready'));
+        const kind = sidecar.kind ?? 'video';
+        const ext = (await storedExt(artifactId, kind, sidecar.ext)) ?? sidecar.ext;
+        return path.join(workspaceRoot, artifactRelPath(artifactId, kind, ext));
     };
     const getKind = async (artifactId) => {
         const meta = await loadMeta(artifactId);
@@ -280,6 +549,90 @@ export function createLocalStorage(opts) {
         const meta = await loadMeta(artifactId);
         return meta?.name ?? null;
     };
+    /** Straight from the sidecar, never the cache: its flags change after the cache was filled. */
+    const describeArtifact = async (artifactId) => {
+        const sidecar = await readSidecar(artifactId);
+        if (!sidecar)
+            return null;
+        return sidecarToMeta(artifactId, sidecar, await lastActivity(artifactId, sidecar));
+    };
+    const patchArtifact = (artifactId, patch) => withSidecarLock(artifactId, async () => {
+        if (patch.ext !== undefined && !EXTENSION_REGEX.test(patch.ext)) {
+            throw new TypeError(`patchArtifact: invalid ext ${JSON.stringify(patch.ext)}`);
+        }
+        const sidecar = await readSidecar(artifactId);
+        if (!sidecar)
+            return false;
+        // Another pass already recorded its conversion, or the id was removed and reserved again:
+        // this patch belongs to neither.
+        if (patch.unlessConverted && sidecar.converted !== false)
+            return false;
+        if (patch.generation !== undefined && (sidecar.generation ?? null) !== patch.generation)
+            return false;
+        const kind = sidecar.kind ?? 'video';
+        const stored = (ext) => path.join(workspaceRoot, kind, `${artifactId}${ext}`);
+        const ext = patch.ext ?? sidecar.ext;
+        if (patch.file !== undefined) {
+            if (path.dirname(path.resolve(patch.file)) !== path.join(workspaceRoot, kind)) {
+                throw new TypeError('patchArtifact: `file` must be in the artifact\'s kind directory');
+            }
+            await fs.rename(patch.file, stored(ext));
+        }
+        const next = { ...sidecar };
+        if (patch.acknowledged !== undefined)
+            next.acknowledged = patch.acknowledged;
+        if (patch.converted !== undefined)
+            next.converted = patch.converted;
+        if (patch.webReady !== undefined)
+            next.webReady = patch.webReady;
+        if (patch.ext !== undefined && patch.ext !== sidecar.ext) {
+            next.sourceExt = sidecar.sourceExt ?? sidecar.ext;
+            next.ext = patch.ext;
+        }
+        if (patch.outcome !== undefined) {
+            if (patch.outcome === null)
+                delete next.outcome;
+            else
+                next.outcome = patch.outcome;
+        }
+        await writeSidecar(artifactId, next);
+        // The cache holds nothing a patch changes, but a `ready` flip elsewhere must not be undone
+        // by a stale entry either — keep it consistent with what was just written.
+        cacheSet(artifactId, sidecarToCachedMeta(next, next.status === 'ready'));
+        // The sidecar names the new file: the one under the old extension goes. (A crash before
+        // this leaves it for `remove`, which deletes `sourceExt` too. A sidecar copy that still
+        // names it finds the new file instead: `storedExt`.)
+        if (ext !== sidecar.ext)
+            await fs.rm(stored(sidecar.ext), { force: true });
+        return true;
+    });
+    async function* listRelated(artifactId) {
+        if (!isUuid(artifactId))
+            return;
+        let names;
+        try {
+            names = await fs.readdir(relatedDir(artifactId));
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                return;
+            throw err;
+        }
+        for (const relatedId of names) {
+            if (!isUuid(relatedId))
+                continue;
+            const sidecar = await readSidecar(relatedId);
+            if (!sidecar || sidecar.relatedTo !== artifactId)
+                continue; // A marker whose artifact is gone.
+            yield {
+                artifactId: relatedId,
+                kind: sidecar.kind ?? 'video',
+                relatedTo: artifactId,
+                ready: sidecar.status === 'ready',
+                updatedAt: await lastActivity(relatedId, sidecar),
+            };
+        }
+    }
     /**
      * Walk the sidecars. A sidecar is rewritten only when its upload finishes, so its mtime is
      * when the upload started (still uploading) or when it finished (ready). An upload in flight
@@ -336,7 +689,7 @@ export function createLocalStorage(opts) {
         workspaceRoot,
         initialize,
         reserveUpload,
-        resolve,
+        resolve: (artifactId) => resolve(artifactId),
         markReady,
         remove,
         getLocalPath,
@@ -345,6 +698,9 @@ export function createLocalStorage(opts) {
         getChecksum,
         getName,
         listArtifacts,
+        describeArtifact,
+        patchArtifact,
+        listRelated,
     };
 }
 //# sourceMappingURL=local.js.map