@platless/axom-cli 0.1.0 → 0.5.9

package/dist/workstation/files/media/scheduler.js

@@ -0,0 +1,551 @@
+import * as fs from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { MediaCache } from './cache.js';
+import { probeSource, encodeGeneration } from './encoding.js';
+import { MediaEstimator, choosePreparation } from './estimator.js';
+import { DEFAULT_MEDIA_POLICY } from './types.js';
+const id = () => randomUUID().replaceAll('-', '');
+const wire = ({ file, ...object }) => object;
+// The 30 fps preview can end a partial frame before the container timestamp.
+const EOF_FRAME_TOLERANCE_MS = 50;
+const matches = (a, b) => a.version === b.version && a.sourcePath === b.sourcePath && a.snapshot === b.snapshot && a.recipe === b.recipe;
+/** One encoder admission for v1 and v2; source descriptors outlive the short tools transaction. */
+export class MediaConsumerExpiredError extends Error {
+    constructor() { super('Media consumer was released or expired'); this.name = 'MediaConsumerExpiredError'; }
+}
+export class MediaScheduler {
+    cache;
+    directory;
+    policy;
+    jobs = new Map();
+    consumers = new Map();
+    finite = [];
+    active;
+    running;
+    closed = false;
+    timer;
+    now;
+    probe;
+    encode;
+    constructor(cache, directory, policy, deps) {
+        this.cache = cache;
+        this.directory = directory;
+        this.policy = policy;
+        this.now = deps.now ?? Date.now;
+        this.probe = deps.probe ?? probeSource;
+        this.encode = deps.encode ?? encodeGeneration;
+        this.timer = setInterval(() => { void this.tick().catch(() => { }); }, 250);
+        this.timer.unref();
+    }
+    static async create(directory, policy = DEFAULT_MEDIA_POLICY, deps = {}) {
+        return new MediaScheduler(await MediaCache.open(directory, policy), directory, policy, deps);
+    }
+    /** Encodes running or admitted to run (the active one plus queued finite preparations): work a host restart would lose. */
+    get runningEncodes() { return (this.active ? 1 : 0) + this.finite.length; }
+    pending() { return [...this.jobs.values()].filter(j => !j.range && j.state !== 'failed').length + this.finite.length + (this.active && !this.active.job ? 1 : 0); }
+    async open(input, key, consumerId, hls) {
+        let retained = false;
+        try {
+            if (this.closed)
+                throw new Error('Workstation media stopped');
+            const existing = this.consumers.get(consumerId);
+            if (existing) {
+                if (!matches(existing.job.key, key) || existing.hls !== hls)
+                    throw new Error('Media consumer identity is already in use');
+                existing.expires = this.now() + this.policy.consumerLeaseMs;
+                return await this.describe(existing);
+            }
+            if (this.consumers.size >= 256)
+                throw new Error('Media resource limit reached');
+            let job = this.jobs.get(key.version);
+            if (job && !matches(job.key, key))
+                throw new Error('Media source changed');
+            if (job?.state === 'failed' && !job.consumers.size) {
+                this.jobs.delete(key.version);
+                await job.input.close();
+                job = undefined;
+            }
+            if (!job) {
+                const generations = await this.cache.lookup(key);
+                // Another open may have finished while the filesystem lookup awaited.
+                job = this.jobs.get(key.version);
+                if (!job) {
+                    const range = generations.flatMap(g => g.objects).find(o => o.type === 'range' && o.startMs === 0);
+                    const legacy = range ? null : await this.cache.lookupLegacy(key.legacyVersion ?? key.version);
+                    if (!range && !legacy && this.pending() >= this.policy.maxJobs)
+                        throw new Error('Workstation media queue is full; try again shortly');
+                    job = { key, input, consumers: new Map(), generations, probe: generations.find(g => g.probe)?.probe, range: range ?? legacy?.object, legacy: legacy?.object, state: range || legacy ? 'ready' : 'queued', created: this.now() };
+                    if (range || legacy)
+                        job.probe = { kind: legacy?.kind ?? (range.extension === 'mp4' ? 'video' : 'audio'), durationMs: legacy?.durationMs ?? range.endMs, durationAccuracy: 'exact', sourceBytes: 0, codec: 'cached', ffmpegVersion: 'cached' };
+                    this.jobs.set(key.version, job);
+                    retained = true;
+                }
+            }
+            const consumer = { id: consumerId, job, hls, position: 0, demand: 0, playing: true, revision: 0, explicit: true, requestedAt: this.now(), expires: this.now() + this.policy.consumerLeaseMs, allowed: new Map() };
+            job.consumers.set(consumerId, consumer);
+            job.releaseAt = undefined;
+            this.consumers.set(consumerId, consumer);
+            this.assignCached(consumer);
+            this.kick();
+            return await this.describe(consumer);
+        }
+        finally {
+            if (!retained)
+                await input.close();
+        }
+    }
+    consumer(key, consumerId) {
+        const c = this.consumers.get(consumerId);
+        if (!c)
+            throw new MediaConsumerExpiredError();
+        if (!matches(c.job.key, key))
+            throw new Error('Media consumer identity mismatch');
+        c.expires = this.now() + this.policy.consumerLeaseMs;
+        return c;
+    }
+    async refreshRetained(job) {
+        const retained = await this.cache.lookup(job.key);
+        const active = this.active?.job === job ? this.active.generation : undefined;
+        job.generations = retained.map(g => { if (g.id === active?.id) {
+            active.objects = g.objects;
+            return active;
+        } return g; });
+        if (active && !job.generations.some(g => g.id === active.id))
+            job.generations.push(active);
+        for (const c of job.consumers.values()) {
+            if (c.generation)
+                c.generation = job.generations.find(g => g.id === c.generation.id);
+            if (c.preparing)
+                c.preparing = job.generations.find(g => g.id === c.preparing.id);
+        }
+        if (job.range && !job.legacy && !job.generations.some(g => g.objects.some(o => o.id === job.range.id))) {
+            job.range = undefined;
+            job.state = 'queued';
+        }
+    }
+    assignCached(c) {
+        const generations = c.job.generations.filter(g => g.objects.some(o => o.type === 'segment' && o.startMs <= c.position && (o.endMs > c.position || (c.position === c.job.probe?.durationMs && o.endMs === c.position))));
+        if (generations.length) {
+            c.generation = generations.at(-1);
+            c.explicit = false;
+        }
+    }
+    async status(key, consumerId) { const c = this.consumer(key, consumerId); await this.refreshRetained(c.job); this.kick(); return this.describe(c); }
+    async seek(key, consumerId, positionMs, revision) {
+        const c = this.consumer(key, consumerId);
+        if (!Number.isSafeInteger(positionMs) || positionMs < 0 || positionMs > 21600000 || !Number.isSafeInteger(revision) || revision < 0)
+            throw new Error('Invalid media seek');
+        if (revision <= c.revision)
+            return this.describe(c);
+        if (c.job.probe?.durationMs != null && positionMs > c.job.probe.durationMs)
+            throw new Error('Invalid media seek');
+        await this.refreshRetained(c.job);
+        c.revision = revision;
+        c.position = positionMs;
+        c.demand = positionMs;
+        c.explicit = true;
+        c.requestedAt = this.now();
+        c.generation = undefined;
+        c.preparing = undefined;
+        c.playlist = undefined;
+        c.allowed.clear();
+        await this.cache.unpin(c.id);
+        this.assignCached(c);
+        this.kick();
+        return this.describe(c);
+    }
+    async interest(key, consumerId, positionMs, playing) {
+        const c = this.consumer(key, consumerId);
+        if (!Number.isSafeInteger(positionMs) || positionMs < 0 || positionMs > 21600000 || typeof playing !== 'boolean')
+            throw new Error('Invalid media interest');
+        c.position = positionMs;
+        if (!playing)
+            c.demand = positionMs;
+        c.playing = playing;
+        this.kick();
+    }
+    async object(key, consumerId, objectId, offset, length) {
+        const c = this.consumer(key, consumerId);
+        if ((c.allowed.get(objectId) ?? 0) <= Date.now())
+            throw new Error('Media object is not available to this consumer');
+        const object = c.job.range?.id === objectId ? c.job.range : c.job.generations.flatMap(g => g.objects).find(o => o.id === objectId);
+        if (!object)
+            throw new Error('Media object is unavailable');
+        let bytes;
+        if (c.job.legacy?.id === objectId) {
+            if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(length) || length < 1 || length > 256 * 1024)
+                throw new Error('Invalid media read');
+            const handle = await fs.open(object.file, constants.O_RDONLY | constants.O_NOFOLLOW);
+            try {
+                const stat = await handle.stat();
+                if (!stat.isFile() || stat.size !== object.size)
+                    throw new Error('Media cache changed');
+                bytes = Buffer.alloc(Math.min(length, Math.max(0, object.size - offset)));
+                const r = await handle.read(bytes, 0, bytes.length, offset);
+                bytes = bytes.subarray(0, r.bytesRead);
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        else
+            bytes = await this.cache.read(key, objectId, offset, length);
+        if (c.playing)
+            c.demand = Math.max(c.demand, object.endMs);
+        this.kick();
+        return { objectId, offset, size: object.size, etag: object.etag, data: bytes.toString('base64'), eof: offset + bytes.length >= object.size };
+    }
+    /** Cleanup only: opaque consumer/version owns the job even if its source/root disappeared. */
+    async releaseIdentity(version, consumerId) {
+        const c = this.consumers.get(consumerId);
+        if (!c)
+            return;
+        if (c.job.key.version !== version)
+            throw new Error('Media consumer identity mismatch');
+        await this.release(c.job.key, consumerId);
+    }
+    async release(key, consumerId) {
+        const c = this.consumers.get(consumerId);
+        if (!c)
+            return;
+        if (!matches(c.job.key, key))
+            throw new Error('Media consumer identity mismatch');
+        this.consumers.delete(c.id);
+        c.job.consumers.delete(c.id);
+        await this.cache.unpin(c.id);
+        if (!c.job.consumers.size)
+            c.job.releaseAt = this.now() + this.policy.releaseGraceMs;
+    }
+    async tick() {
+        const now = this.now();
+        for (const c of [...this.consumers.values()])
+            if (c.expires <= now)
+                await this.release(c.job.key, c.id);
+        for (const job of [...this.jobs.values()])
+            if (job.releaseAt !== undefined && job.releaseAt <= now) {
+                if (this.active?.job === job) {
+                    this.active.stopped = true;
+                    this.active.controller.abort();
+                }
+                else {
+                    this.jobs.delete(job.key.version);
+                    await job.input.close();
+                }
+            }
+        this.kick();
+    }
+    runFinite(run, signal) {
+        if (this.closed)
+            return Promise.reject(new Error('Workstation media stopped'));
+        if (this.pending() >= this.policy.maxJobs)
+            return Promise.reject(new Error('Workstation media queue is full'));
+        return new Promise((resolve, reject) => {
+            const controller = new AbortController();
+            const task = { run, controller, resolve: value => resolve(value), reject, cleanup: () => signal.removeEventListener('abort', abort) };
+            const abort = () => { controller.abort(); const index = this.finite.indexOf(task); if (index >= 0) {
+                this.finite.splice(index, 1);
+                task.cleanup();
+                reject(new Error('Media preparation cancelled'));
+            } };
+            signal.addEventListener('abort', abort, { once: true });
+            this.finite.push(task);
+            if (signal.aborted)
+                abort();
+            this.kick();
+        });
+    }
+    fullGeneration(job) {
+        return job.generations.find(g => {
+            if (!g.complete || !g.sourceComplete || g.sourceOffsetMs !== 0)
+                return false;
+            let end = 0;
+            const objects = g.objects.filter(o => o.type === 'segment').sort((a, b) => a.startMs - b.startMs);
+            for (const o of objects) {
+                if (o.startMs > end + 1)
+                    return false;
+                end = Math.max(end, o.endMs);
+            }
+            return objects.length > 0 && end >= (job.probe?.durationMs ?? objects.at(-1).endMs) - EOF_FRAME_TOLERANCE_MS;
+        });
+    }
+    candidate(c) {
+        const j = c.job;
+        if (j.range || j.state === 'failed' || !j.consumers.size)
+            return;
+        if (!c.mode && !j.finiteUnavailable && this.fullGeneration(j))
+            return { job: j, consumer: c, start: 0, rank: 0, requestedAt: c.requestedAt, revision: c.revision };
+        const end = this.frontier(c);
+        const desired = c.playing ? Math.max(c.position, c.demand) : c.position;
+        if (j.probe?.durationMs != null && end >= j.probe.durationMs && !c.explicit)
+            return;
+        if (!c.explicit && j.probe?.durationMs != null && end >= j.probe.durationMs - EOF_FRAME_TOLERANCE_MS && j.generations.some(g => g.complete && g.sourceComplete && g.sourceOffsetMs <= end && (g.objects.at(-1)?.endMs ?? Infinity) <= end))
+            return;
+        if (c.hls && !c.explicit && end - desired >= this.policy.lookaheadMs)
+            return;
+        return { job: j, consumer: c, start: c.explicit ? (c.position === j.probe?.durationMs ? Math.max(0, c.position - 4000) : c.position) : end, rank: c.explicit ? 0 : c.playing && end - desired < 12000 ? 1 : 2, requestedAt: c.requestedAt, revision: c.revision };
+    }
+    frontier(c) {
+        // Downloaded data is not a played position. Keep a conservative full lookahead behind
+        // demand so background decoders can advance without pinning the entire watched prefix.
+        let end = Math.max(c.position, c.playing ? c.demand - this.policy.lookaheadMs : 0);
+        const objects = c.job.generations.flatMap(g => g.objects).filter(o => o.type === 'segment').sort((a, b) => a.startMs - b.startMs);
+        for (const o of objects) {
+            if (o.startMs > end)
+                break;
+            if (o.endMs > end)
+                end = o.endMs;
+        }
+        return end;
+    }
+    candidates() { return [...this.consumers.values()].map(c => this.candidate(c)).filter((c) => !!c).sort((a, b) => a.rank - b.rank || a.requestedAt - b.requestedAt); }
+    kick() {
+        if (this.closed || this.active)
+            return;
+        const candidate = this.candidates()[0];
+        const finite = this.finite[0];
+        if (!candidate && !finite)
+            return;
+        const active = { controller: new AbortController(), stopped: false, started: this.now() };
+        this.active = active;
+        this.running = (async () => {
+            if (finite) {
+                this.finite.shift();
+                active.controller = finite.controller;
+                try {
+                    finite.resolve(await finite.run(finite.controller.signal));
+                }
+                catch (error) {
+                    finite.reject(error);
+                }
+                finally {
+                    finite.cleanup();
+                }
+            }
+            else if (candidate) {
+                active.job = candidate.job;
+                active.target = candidate.consumer;
+                await this.produce(candidate, active);
+            }
+        })().catch(() => { }).finally(async () => {
+            if (active.job?.releaseAt !== undefined && active.job.releaseAt <= this.now()) {
+                this.jobs.delete(active.job.key.version);
+                await active.job.input.close();
+            }
+            if (this.active === active)
+                this.active = undefined;
+            this.kick();
+        });
+    }
+    async produce(candidate, active) {
+        const job = candidate.job;
+        let claim;
+        try {
+            if (!job.verifiedProbe || !job.probe) {
+                job.state = 'probing';
+                job.probe = await this.probe(job.input, active.controller.signal);
+                job.verifiedProbe = true;
+            }
+            if (job.probe.kind === 'image')
+                throw new Error('Images use completed finite preparation');
+            job.estimator ??= await MediaEstimator.load(this.directory, job.probe.ffmpegVersion, job.key.recipe);
+            job.estimate = job.estimator.predict(job.probe);
+            job.state = 'preparing';
+            claim = await this.cache.claimWriter(job.key);
+            // Open/probe is asynchronous. A seek received during it supersedes the captured
+            // target; it must not be cleared by the old producer's initial assignment.
+            if (candidate.consumer.revision !== candidate.revision)
+                return;
+            const reusable = this.fullGeneration(job);
+            if (reusable && !job.finiteUnavailable && !candidate.consumer.mode) {
+                job.range = await this.cache.finalizeRange(job.key, reusable.id, active.controller.signal) ?? undefined;
+                job.finiteUnavailable = !job.range;
+                if (!job.range && [...job.consumers.values()].some(c => !c.hls))
+                    throw new Error('Not enough cache space for a completed media preview');
+                job.state = job.range ? 'ready' : 'streamable';
+                return;
+            }
+            for (const old of job.generations)
+                if (!old.complete) {
+                    old.complete = true;
+                    old.sourceComplete = false;
+                    await this.cache.finishGeneration(job.key, old);
+                }
+            const generation = { id: id(), sourceOffsetMs: candidate.start, timestampOriginMs: 0, targetDurationMs: 4000, objects: [], complete: false, sourceComplete: false, createdAtMs: this.now(), probe: job.probe };
+            active.generation = generation;
+            job.generations.push(generation);
+            const output = await this.cache.createGeneration(job.key, generation.id);
+            for (const c of job.consumers.values()) {
+                if (c.explicit && (c.position === candidate.start || (c === candidate.consumer && c.revision === candidate.revision))) {
+                    c.generation = generation;
+                    c.preparing = undefined;
+                    c.explicit = false;
+                }
+                else if (c === candidate.consumer && c.revision === candidate.revision)
+                    c.preparing = generation;
+            }
+            const started = this.now();
+            let calibrated = false;
+            try {
+                const result = await this.encode(job.input, job.probe, candidate.start, output, active.controller.signal, async (object) => {
+                    await this.cache.publish(job.key, generation, object);
+                    generation.objects.push(object);
+                    await this.refreshRetained(job);
+                    for (const c of job.consumers.values())
+                        if (!c.explicit && c.generation !== generation && c.position < object.endMs && this.frontier(c) >= object.endMs)
+                            c.preparing = generation;
+                    if (!calibrated && this.now() > started) {
+                        calibrated = true;
+                        await job.estimator.observe(job.probe, { sourceMs: object.endMs - candidate.start, elapsedMs: this.now() - started, sourceBytes: Math.round(job.probe.sourceBytes * (object.endMs - candidate.start) / job.probe.durationMs), finalizationMs: 0 });
+                        job.estimate = job.estimator.predict(job.probe);
+                    }
+                    job.state = 'streamable';
+                    for (const c of job.consumers.values())
+                        if (c.generation === generation)
+                            await this.describe(c);
+                    const current = [...job.consumers.values()].filter(c => c.generation === generation || c.preparing === generation);
+                    const end = object.endMs;
+                    const need = current.some(c => !c.hls || end - (c.playing ? Math.max(c.position, c.demand) : c.position) < this.policy.lookaheadMs);
+                    const waiting = this.candidates().find(c => c.job !== job || (c.consumer.generation !== generation && c.consumer.preparing !== generation));
+                    const currentRank = Math.min(...current.map(c => this.candidate(c)?.rank ?? 3), 3);
+                    const mode = choosePreparation(job.estimate, false, true, this.now() - started);
+                    const windowComplete = (mode === 'hls-window' || current.some(c => c.mode === 'hls-window')) && end - generation.sourceOffsetMs >= 8000;
+                    // Stop only at a published boundary. Other consumers retain their immutable generation.
+                    const finiteRequired = [...job.consumers.values()].some(c => !c.hls);
+                    const preparingFinite = [...job.consumers.values()].some(c => !c.mode && ['range', 'calibrating'].includes(choosePreparation(job.estimate, false, c.hls, this.now() - started)));
+                    if (!finiteRequired && end < job.probe.durationMs - EOF_FRAME_TOLERANCE_MS && ((!preparingFinite && ((!need && job.consumers.size) || windowComplete)) || (waiting && waiting.rank < currentRank))) {
+                        active.stopped = true;
+                        active.controller.abort();
+                    }
+                }, () => { });
+                generation.complete = result.complete;
+                generation.sourceComplete = result.sourceComplete;
+            }
+            catch (error) {
+                if (!active.stopped)
+                    throw error;
+                generation.complete = true;
+                generation.sourceComplete = false;
+            }
+            await this.cache.finishGeneration(job.key, generation);
+            if (generation.sourceComplete && generation.sourceOffsetMs === 0) {
+                const finalized = this.now();
+                job.range = await this.cache.finalizeRange(job.key, generation.id, active.controller.signal) ?? undefined;
+                if (!job.range && [...job.consumers.values()].some(c => !c.hls))
+                    throw new Error('Not enough cache space for a completed media preview');
+                job.finiteUnavailable = !job.range;
+                if (this.now() > started)
+                    await job.estimator.observe(job.probe, { sourceMs: job.probe.durationMs, elapsedMs: Math.max(1, finalized - started), sourceBytes: job.probe.sourceBytes, finalizationMs: Math.max(0, this.now() - finalized) });
+            }
+            job.state = job.range ? 'ready' : 'streamable';
+        }
+        catch (error) {
+            if (!active.stopped) {
+                job.state = 'failed';
+                job.error = error.message.slice(0, 512);
+                await job.input.close();
+            }
+        }
+        finally {
+            await claim?.release();
+        }
+    }
+    /** Encoder windows are scheduling units, not native-player lifetimes. Append contiguous
+     * published windows to one consumer playlist; only an explicit seek replaces its URI. */
+    extendPlaylist(c) {
+        const playlist = c.playlist;
+        const candidates = c.job.generations.flatMap(g => g.objects.filter(o => o.type === 'segment').map(o => ({ g, o })));
+        while (playlist.objects.length < 256) {
+            const next = candidates.find(({ o }) => o.startMs === playlist.end && o.endMs > playlist.end);
+            if (!next)
+                break;
+            const previous = playlist.objects.at(-1);
+            const continuous = previous && next.o.timestamp90k === previous.timestamp90k + (previous.endMs - previous.startMs) * 90;
+            playlist.objects.push({ ...next.o, sequence: playlist.nextSequence++, discontinuity: next.g.id !== playlist.lastGeneration && !continuous });
+            playlist.lastGeneration = next.g.id;
+            playlist.end = next.o.endMs;
+        }
+        playlist.sourceComplete = c.job.generations.some(g => g.id === playlist.lastGeneration && g.complete && g.sourceComplete && playlist.end >= (c.job.probe?.durationMs ?? Infinity) - EOF_FRAME_TOLERANCE_MS);
+    }
+    async describe(c) {
+        const j = c.job;
+        const g = c.generation;
+        const probe = j.probe;
+        const base = { state: j.state, version: j.key.version, kind: probe?.kind, sourceDurationMs: probe?.durationMs, durationAccuracy: probe?.durationAccuracy,
+            estimatedPreparationMs: j.estimate?.serviceMs, queueWaitMs: j.state === 'queued' ? Math.max(0, this.now() - c.requestedAt) : 0,
+            ...(j.error ? { error: j.error, errorCode: 'media-preparation-failed' } : {}) };
+        // Do not replace an already playing HLS generation with a future finite derivative.
+        if (j.range && (!c.hls || (!g && !c.playlist) || !c.mode)) {
+            c.allowed.set(j.range.id, Date.now() + 60000);
+            await this.cache.pin(c.id, [j.range.id], Date.now() + 60000);
+            return { ...base, state: 'ready', delivery: 'range', objects: [wire(j.range)], size: j.range.size, mimeType: j.range.mimeType, extension: j.range.extension, generationComplete: true, sourceComplete: true };
+        }
+        if (!g && !c.playlist)
+            return { ...base, state: j.state === 'failed' ? 'failed' : j.state === 'probing' ? 'probing' : 'queued' };
+        const mode = c.mode ?? choosePreparation(j.estimate ?? { serviceMs: null, firstPlayableMs: null, confidence: 'low', producerSpeed: null }, false, c.hls, this.active?.job === j ? this.now() - this.active.started : 0);
+        const lower = Math.max(0, c.position - 12000, c.playing ? c.demand - this.policy.lookaheadMs : 0);
+        const upper = Math.max(c.position, c.playing ? c.demand : 0) + this.policy.lookaheadMs;
+        if (c.playlist) {
+            while (c.playlist.objects[0]?.endMs <= lower) {
+                if (c.playlist.objects.shift().discontinuity)
+                    c.playlist.discontinuitySequence++;
+            }
+            this.extendPlaylist(c);
+        }
+        const all = c.playlist?.objects ?? g.objects.filter(o => o.type === 'segment');
+        const after = all.filter(o => o.endMs > lower);
+        let objects = after.filter(o => o.startMs < upper).slice(0, 256);
+        const span = objects.length ? objects.at(-1).endMs - objects[0].startMs : 0;
+        const streamable = c.hls && objects.length > 0 && (!!c.playlist || (g.complete && (g.sourceOffsetMs > 0 || !g.sourceComplete || !!c.mode || j.finiteUnavailable)) || ((mode === 'hls-growing') && span >= 12000));
+        if (streamable) {
+            c.mode ??= mode === 'hls-growing' ? 'hls-growing' : 'hls-window';
+            if (!c.playlist) {
+                c.playlist = { id: g.id, offset: g.sourceOffsetMs, objects: [], end: objects[0].startMs, nextSequence: objects[0].sequence, lastGeneration: g.id, discontinuitySequence: 0, sourceComplete: false };
+                this.extendPlaylist(c);
+                objects = c.playlist.objects.filter(o => o.endMs > lower && o.startMs < upper);
+            }
+        }
+        for (const [object, expiry] of c.allowed)
+            if (expiry <= Date.now())
+                c.allowed.delete(object);
+        const retainedSpan = objects.length ? objects.at(-1).endMs - objects[0].startMs : 0;
+        const retainedUntil = Date.now() + Math.max(16000, retainedSpan + 4000);
+        for (const object of objects)
+            c.allowed.set(object.id, Math.max(c.allowed.get(object.id) ?? 0, retainedUntil));
+        await this.cache.pin(c.id, objects.map(o => o.id), retainedUntil);
+        return { ...base, state: j.state === 'failed' ? 'failed' : streamable ? 'streamable' : 'preparing', delivery: 'hls', generationId: c.playlist?.id ?? g.id, generationOffsetMs: c.playlist?.offset ?? g.sourceOffsetMs, targetDurationMs: g?.targetDurationMs ?? 4000,
+            generationComplete: c.playlist?.sourceComplete ?? g.complete, sourceComplete: c.playlist?.sourceComplete ?? g.sourceComplete, discontinuitySequence: c.playlist?.discontinuitySequence ?? 0,
+            objects: objects.map(wire), encodedIntervals: intervals(j.generations.flatMap(g => g.objects)) };
+    }
+    async reserveLegacy(output, bytes) { return this.cache.reserveLegacy(output, bytes); }
+    async pinLegacy(version) { await this.cache.pin(`legacy:${version}`, [version.slice(0, 32)], Date.now() + 60000); await this.cache.unpin(`legacy:${version}`); }
+    async trimCache() { await this.cache.trim(Date.now()); }
+    async dispose() {
+        this.closed = true;
+        clearInterval(this.timer);
+        this.active?.controller.abort();
+        for (const finite of this.finite) {
+            finite.cleanup();
+            finite.reject(new Error('Workstation media stopped'));
+        }
+        this.finite = [];
+        await this.running;
+        for (const c of this.consumers.values())
+            await this.cache.unpin(c.id);
+        this.consumers.clear();
+        for (const j of this.jobs.values())
+            await j.input.close();
+        this.jobs.clear();
+    }
+}
+function intervals(objects) {
+    const merged = [];
+    for (const o of objects.filter(o => o.type === 'segment').sort((a, b) => a.startMs - b.startMs)) {
+        const last = merged.at(-1);
+        if (last && last.endMs >= o.startMs)
+            last.endMs = Math.max(last.endMs, o.endMs);
+        else
+            merged.push({ startMs: o.startMs, endMs: o.endMs });
+    }
+    return merged.slice(-64);
+}

package/dist/workstation/files/media/types.js

@@ -0,0 +1,5 @@
+export const DEFAULT_MEDIA_POLICY = {
+    finiteThresholdMs: 10_000, maxVersionBytes: 512 * 1024 * 1024, maxCacheBytes: 2 * 1024 * 1024 * 1024,
+    ttlMs: 24 * 60 * 60 * 1000, maxJobs: 8, consumerLeaseMs: 60_000, releaseGraceMs: 5_000,
+    lookaheadMs: 60_000, noProgressMs: 30_000,
+};

package/dist/workstation/files/scope.js

@@ -0,0 +1,45 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { FileError } from './errors.js';
+const OPERATIONS = {
+    'request-root': new Set(['read', 'write', 'list', 'mkdir']),
+    'configured-roots': new Set(['read', 'list', 'find', 'media', 'mkdir', 'rename', 'delete', 'upload']),
+    'read-only': new Set(['read', 'list', 'find', 'media']),
+    'filesystem': new Set(['read', 'list', 'find', 'media', 'mkdir', 'rename', 'delete', 'upload']),
+};
+export const READ_ONLY = Object.freeze({ kind: 'read-only' });
+export async function filesystemScope(home) {
+    home = await fs.realpath(home);
+    return Object.freeze({ kind: 'filesystem', home, roots: Object.freeze([home, path.parse(home).root]) });
+}
+/** The server-given root must be absolute: a relative one would resolve against whatever directory a section pinned. */
+export function requestRoot(root) {
+    if (typeof root !== 'string' || !path.isAbsolute(root) || root.includes('\0')) {
+        throw new FileError('invalid_path', 'Workspace root must be an absolute path');
+    }
+    return Object.freeze({ kind: 'request-root', root });
+}
+/** Canonical home plus canonical workspace roots (each must be a directory), exactly as the keeper computed them. */
+export async function configuredRoots(home, roots) {
+    home = await fs.realpath(home);
+    const canonical = new Set([home]);
+    for (const root of roots) {
+        const real = await fs.realpath(root);
+        if (!(await fs.stat(real)).isDirectory())
+            throw new Error('File root must be a directory');
+        canonical.add(real);
+    }
+    return Object.freeze({ kind: 'configured-roots', roots: Object.freeze([...canonical]), home });
+}
+export function scopeAllows(scope, operation) {
+    return OPERATIONS[scope.kind].has(operation);
+}
+export function assertScopeAllows(scope, operation) {
+    if (scopeAllows(scope, operation))
+        return;
+    if (scope.kind === 'read-only')
+        throw new FileError('permission_denied', 'Read-only file access cannot modify files');
+    throw new FileError('invalid_argument', 'File operation is not available in this scope');
+}
+/** `target` is `root` or below it (both canonical absolute paths). */
+export function inside(target, root) { return target === root || target.startsWith(root + path.sep); }