@hyperframes/engine 0.7.27 → 0.7.29

package/dist/config.d.ts

@@ -153,16 +153,19 @@ export interface EngineConfig {
     /**
      * Directory where the content-addressed extraction cache persists frame
      * bundles keyed on (path, mtime, size, mediaStart, duration, fps, format).
-     * Undefined disables caching — extraction runs into the render's workDir
-     * and cleanup removes it when the render ends, preserving the pre-cache
-     * behaviour.
+     * Defaults on under the OS temp directory:
+     * `<tmpdir>/hyperframes-extract-cache-<uid>`.
      *
-     * **Single-writer.** The cache is not safe for concurrent renders pointing
-     * at the same directory. A `.hf-complete` sentinel prevents another render
-     * from serving an entry that hasn't finished extracting, but individual
-     * frame files are written non-atomically — a second render reading during
-     * the write window can observe a truncated frame. Give each concurrent
-     * render pipeline its own `extractCacheDir`, or gate with an external mutex.
+     * New entries publish atomically: frames are extracted into a unique
+     * partial directory, the `.hf-complete` sentinel is written there, and the
+     * partial directory is renamed into the final key directory. Concurrent
+     * renders against the same cache are safe; at worst, two renders duplicate
+     * ffmpeg work and one rehydrates from the winner.
+     *
+     * Set `HYPERFRAMES_EXTRACT_CACHE_DIR` to a path to override the default, or
+     * to `off`, `none`, `false`, or `0` to disable caching for the process.
+     * When disabled, extraction runs into the render's workDir and cleanup
+     * removes it when the render ends, preserving the pre-cache behaviour.
      *
      * **Network filesystems.** `mtime` resolution on NFS/SMB mounts can be
      * coarser than expected (seconds rather than nanoseconds), which may
@@ -172,6 +175,15 @@ export interface EngineConfig {
      * Env fallback: `HYPERFRAMES_EXTRACT_CACHE_DIR`.
      */
     extractCacheDir?: string;
+    /**
+     * Soft disk budget for `extractCacheDir`, in bytes. The renderer runs a
+     * best-effort LRU sweep after extraction and evicts oldest sentineled
+     * entries until the cache is under this cap, while protecting young entries
+     * that may belong to live renders.
+     *
+     * Env fallback: `HYPERFRAMES_EXTRACT_CACHE_MAX_MB` (megabytes).
+     */
+    extractCacheMaxBytes: number;
     debug: boolean;
 }
 /** Default configuration — sensible for Hyperframes compositions. */

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAE3B,GAAG,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;IAClB,OAAO,EAAE,OAAO,GAAG,UAAU,GAAG,MAAM,CAAC;IACvC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IAGpB,yDAAyD;IACzD,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,sCAAsC;IACtC,cAAc,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,2DAA2D;IAC3D,oBAAoB,EAAE,MAAM,CAAC;IAG7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;;;;OAQG;IACH,cAAc,EAAE,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;IACjD,iBAAiB,EAAE,OAAO,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,qEAAqE;IACrE,eAAe,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,gBAAgB,EAAE,OAAO,CAAC;IAC1B;;;;;;;;OAQG;IACH,aAAa,EAAE,OAAO,CAAC;IACvB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,yBAAyB,EAAE,OAAO,CAAC;IAGnC;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB,qBAAqB,EAAE,OAAO,CAAC;IAC/B;;;;OAIG;IACH,iCAAiC,EAAE,MAAM,CAAC;IAG1C,+DAA+D;IAC/D,mBAAmB,EAAE,MAAM,CAAC;IAC5B,wEAAwE;IACxE,oBAAoB,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,sBAAsB,EAAE,MAAM,CAAC;IAG/B,kEAAkE;IAClE,GAAG,EAAE;QAAE,QAAQ,EAAE,KAAK,GAAG,IAAI,CAAA;KAAE,GAAG,KAAK,CAAC;IACxC,yEAAyE;IACzE,aAAa,EAAE,OAAO,CAAC;IAGvB,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,sBAAsB,EAAE,MAAM,CAAC;IAC/B;;;;;OAKG;IACH,6BAA6B,EAAE,MAAM,CAAC;IAGtC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;;;;;OAQG;IACH,qBAAqB,EAAE,MAAM,CAAC;IAG9B,kDAAkD;IAClD,aAAa,EAAE,OAAO,CAAC;IACvB,mDAAmD;IACnD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAG7B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAGzB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,qEAAqE;AACrE,eAAO,MAAM,cAAc,EAAE,YA+C5B,CAAC;AAqBF;;;;;;;;;;GAUG;AACH,wBAAgB,kCAAkC,CAChD,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACtC,MAAM,CAYR;AAgBD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CA+I7E"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAWH;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAE3B,GAAG,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;IAClB,OAAO,EAAE,OAAO,GAAG,UAAU,GAAG,MAAM,CAAC;IACvC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IAGpB,yDAAyD;IACzD,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,sCAAsC;IACtC,cAAc,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,2DAA2D;IAC3D,oBAAoB,EAAE,MAAM,CAAC;IAG7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;;;;OAQG;IACH,cAAc,EAAE,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;IACjD,iBAAiB,EAAE,OAAO,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,qEAAqE;IACrE,eAAe,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,gBAAgB,EAAE,OAAO,CAAC;IAC1B;;;;;;;;OAQG;IACH,aAAa,EAAE,OAAO,CAAC;IACvB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,yBAAyB,EAAE,OAAO,CAAC;IAGnC;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB,qBAAqB,EAAE,OAAO,CAAC;IAC/B;;;;OAIG;IACH,iCAAiC,EAAE,MAAM,CAAC;IAG1C,+DAA+D;IAC/D,mBAAmB,EAAE,MAAM,CAAC;IAC5B,wEAAwE;IACxE,oBAAoB,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,sBAAsB,EAAE,MAAM,CAAC;IAG/B,kEAAkE;IAClE,GAAG,EAAE;QAAE,QAAQ,EAAE,KAAK,GAAG,IAAI,CAAA;KAAE,GAAG,KAAK,CAAC;IACxC,yEAAyE;IACzE,aAAa,EAAE,OAAO,CAAC;IAGvB,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,sBAAsB,EAAE,MAAM,CAAC;IAC/B;;;;;OAKG;IACH,6BAA6B,EAAE,MAAM,CAAC;IAGtC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;;;;;OAQG;IACH,qBAAqB,EAAE,MAAM,CAAC;IAG9B,kDAAkD;IAClD,aAAa,EAAE,OAAO,CAAC;IACvB,mDAAmD;IACnD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAG7B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;OAOG;IACH,oBAAoB,EAAE,MAAM,CAAC;IAG7B,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,qEAAqE;AACrE,eAAO,MAAM,cAAc,EAAE,YAiD5B,CAAC;AAqBF;;;;;;;;;;GAUG;AACH,wBAAgB,kCAAkC,CAChD,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACtC,MAAM,CAYR;AAgBD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAmK7E"}

package/dist/config.js

@@ -5,6 +5,8 @@
  * env var sprawl with a structured interface. Env vars still work as
  * fallbacks for backward compatibility during migration.
  */
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { getSystemTotalMb, isLowMemorySystem, LOW_MEMORY_TOTAL_MB_THRESHOLD, } from "./services/systemMemory.js";
 import { DEFAULT_VP9_CPU_USED, normalizeVp9CpuUsed } from "./services/vp9Options.js";
 /** Default configuration — sensible for Hyperframes compositions. */
@@ -45,6 +47,7 @@ export const DEFAULT_CONFIG = {
     renderReadyTimeout: 15_000,
     pageNavigationTimeout: 60_000,
     verifyRuntime: true,
+    extractCacheMaxBytes: 2 * 1024 ** 3,
     debug: false,
 };
 /**
@@ -151,6 +154,21 @@ export function resolveConfig(overrides) {
         const raw = env("HF_STATIC_DEDUP")?.trim().toLowerCase();
         return !(raw === "false" || raw === "off" || raw === "0");
     };
+    const resolveExtractCacheDir = () => {
+        const raw = env("HYPERFRAMES_EXTRACT_CACHE_DIR");
+        if (raw === undefined) {
+            return join(tmpdir(), `hyperframes-extract-cache-${process.getuid?.() ?? "u"}`);
+        }
+        const trimmed = raw.trim();
+        const normalized = trimmed.toLowerCase();
+        if (normalized === "off" ||
+            normalized === "none" ||
+            normalized === "false" ||
+            normalized === "0") {
+            return undefined;
+        }
+        return raw;
+    };
     // Env-var layer (backward compat)
     const fromEnv = {
         concurrency: env("PRODUCER_MAX_WORKERS") ? Number(env("PRODUCER_MAX_WORKERS")) : undefined,
@@ -193,7 +211,9 @@ export function resolveConfig(overrides) {
         pageNavigationTimeout: envNum("PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS", DEFAULT_CONFIG.pageNavigationTimeout),
         verifyRuntime: env("PRODUCER_VERIFY_HYPERFRAME_RUNTIME") !== "false",
         runtimeManifestPath: env("PRODUCER_HYPERFRAME_MANIFEST_PATH"),
-        extractCacheDir: env("HYPERFRAMES_EXTRACT_CACHE_DIR"),
+        extractCacheDir: resolveExtractCacheDir(),
+        extractCacheMaxBytes: envNum("HYPERFRAMES_EXTRACT_CACHE_MAX_MB", DEFAULT_CONFIG.extractCacheMaxBytes / 1024 ** 2) *
+            1024 ** 2,
     };
     // Remove undefined values so they don't override defaults
     const cleanEnv = Object.fromEntries(Object.entries(fromEnv).filter(([, v]) => v !== undefined));

package/dist/config.js.map

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

package/dist/services/extractionCache.d.ts

@@ -5,7 +5,8 @@
  * after capture. Repeat renders of the same composition (preview → final,
  * studio iteration) re-extract identical frames from the same source file,
  * burning ffmpeg time that adds no value. This module keys extracted frame
- * bundles on the (path, mtime, size, mediaStart, duration, fps, format)
+ * bundles on the (path, mtime, size, mediaStart, duration, fps, format,
+ * optional transform)
  * tuple so re-renders resolve to a pre-extracted directory instead of
  * re-invoking ffmpeg.
  *
@@ -15,10 +16,14 @@
  * - Cache entries live under `<rootDir>/<SCHEMA_PREFIX><key[0..16]>/` so
  *   `ls` output and tracing logs stay short. Truncation to 16 hex chars
  *   leaves 64 bits of entropy — collision risk at cache scale is negligible.
- * - A completed entry is marked by writing the `.hf-complete` sentinel file
- *   after all frames are on disk. A dir without the sentinel is treated as
- *   absent (stale/abandoned) and re-extracted into a fresh key (the old dir
- *   is left for external gc — the cache owns keys, not deletion policy).
+ * - Frames are extracted into a unique `<entry>.partial-<pid>-<uuid>/` dir.
+ *   Once all frames are written, the partial dir receives the `.hf-complete`
+ *   sentinel and is atomically renamed to the final key dir. Concurrent
+ *   same-key writers may duplicate ffmpeg work, but readers only ever serve
+ *   complete entries.
+ * - The sentinel mtime is touched on hits and used as the cache's LRU clock.
+ *   `gcExtractionCache` evicts by that mtime and also clears old partial dirs
+ *   left behind by crashed writers.
  *
  * ### Versioning
  *
@@ -31,8 +36,16 @@ import type { VideoMetadata } from "../utils/ffprobe.js";
 export declare const FRAME_FILENAME_PREFIX = "frame_";
 /** Sentinel filename written after a cache entry is fully populated. */
 export declare const COMPLETE_SENTINEL = ".hf-complete";
-/** Current schema version. Bump when cache-entry layout changes. */
-export declare const SCHEMA_PREFIX = "hfcache-v2-";
+/** Marker file stamped after each GC sweep; drives the staleness fallback. */
+export declare const GC_MARKER = ".hf-last-gc";
+/**
+ * Current schema version. Bump when the cache-contents invariant changes.
+ * v2 -> v3: one-pass VFR extraction (-fps_mode cfr) replaces the two-pass
+ * VFR-to-CFR re-encode, changing frame contents for VFR sources under
+ * identical key tuples. Without the bump, warm v2 entries (two-pass frames)
+ * would keep being served across the deploy boundary.
+ */
+export declare const SCHEMA_PREFIX = "hfcache-v3-";
 export type CacheFrameFormat = "jpg" | "png";
 export interface CacheKeyInput {
     /** Absolute path to the source video file. Part of the key so moved files
@@ -52,6 +65,8 @@ export interface CacheKeyInput {
     fps: number;
     /** Output image format. */
     format: CacheFrameFormat;
+    /** Optional source transform applied during extraction. */
+    transform?: string;
 }
 export interface CacheEntry {
     /** Absolute path to the cache entry directory. */
@@ -61,11 +76,15 @@ export interface CacheEntry {
 }
 export interface CacheLookup {
     /** Cache entry information — always returned even on a miss so the caller
-     *  can extract directly into `dir` then call `markCacheEntryComplete`. */
+     *  can derive a partial dir and publish it after extraction. */
     entry: CacheEntry;
     /** True when the entry exists AND carries the completion sentinel. */
     hit: boolean;
 }
+export interface CachePublishResult {
+    dir: string;
+    published: boolean;
+}
 /**
  * Read `(mtimeMs, size)` for a path. Returns `null` if the file is missing —
  * callers should skip the cache path for that entry so the extractor surfaces
@@ -88,9 +107,9 @@ export declare function computeCacheKey(input: CacheKeyInput): string;
 export declare function cacheEntryDirName(keyHash: string): string;
 /**
  * Look up a cache entry by key input. Returns the resolved entry path plus a
- * `hit` flag. On miss, callers should extract frames into `entry.dir`
- * (after calling `ensureCacheEntryDir`) and then call `markCacheEntryComplete`
- * once the extraction succeeds.
+ * `hit` flag. On miss, callers should extract frames into a
+ * `partialCacheEntryDir(entry)` directory and publish it with
+ * `publishCacheEntry` once extraction succeeds.
  */
 export declare function lookupCacheEntry(rootDir: string, input: CacheKeyInput): CacheLookup;
 /**
@@ -98,18 +117,54 @@ export declare function lookupCacheEntry(rootDir: string, input: CacheKeyInput):
  * Idempotent: `mkdirSync({recursive:true})` is a no-op when the dir exists.
  */
 export declare function ensureCacheEntryDir(entry: CacheEntry): void;
+/**
+ * Unique render-owned directory used to populate a cache entry before the
+ * atomic publish rename.
+ */
+export declare function partialCacheEntryDir(entry: CacheEntry): string;
+export declare function publishCacheEntry(entry: CacheEntry, partialDir: string): CachePublishResult;
+/**
+ * Update the LRU clock for a complete cache entry. Misses and filesystem
+ * races are harmless: the caller can still use the entry it already found.
+ */
+export declare function touchCacheEntry(entry: CacheEntry): void;
 /**
  * Write the completion sentinel so subsequent lookups treat this entry as a
- * hit. Must be called only after every frame has been written.
+ * hit. Must be called only after every frame has been written. The extractor
+ * now publishes new entries via `publishCacheEntry`; this helper remains
+ * exported for tests and legacy callers that materialize entries directly.
  *
- * Concurrency: lookup→populate→mark is non-atomic. Two concurrent renders of
- * the same key may both miss, both extract into the same dir, and the later
- * writer's frames win. The result is correct (identical inputs yield identical
- * frames) but wasteful. Acceptable for a single-process render pipeline;
- * anyone running concurrent renders against a shared cache root should front
- * it with an external lock.
+ * Concurrency: direct mark is non-atomic and should not be used for shared
+ * writer paths. `publishCacheEntry` writes the sentinel inside a partial dir
+ * and atomically renames it into place, so concurrent writers duplicate work
+ * but never serve torn frames.
  */
 export declare function markCacheEntryComplete(entry: CacheEntry): void;
+export interface GcStats {
+    /** Complete entries evicted by the LRU size sweep. */
+    evictedEntries: number;
+    /** Bytes reclaimed by evicted entries. */
+    evictedBytes: number;
+    /** Aged `.partial-*` dirs (crashed writers) removed. */
+    agedPartialsRemoved: number;
+}
+/**
+ * Opportunistic size-capped LRU cleanup for extracted video frames.
+ *
+ * Scans only direct cache-looking children and never throws. The age guard is
+ * a liveness heuristic, not a lock. Returns counts so the caller can surface
+ * eviction pressure in render observability.
+ */
+/**
+ * Whether the staleness fallback should force a sweep: true when no sweep
+ * marker exists or the last sweep is older than `maxAgeMs`. Lets 100%-warm
+ * workloads (which skip the per-miss sweep) still reclaim space eventually.
+ */
+export declare function gcSweepDue(rootDir: string, maxAgeMs: number): boolean;
+export declare function gcExtractionCache(rootDir: string, opts: {
+    maxBytes: number;
+    minAgeMs: number;
+}): GcStats;
 /**
  * Rebuild the in-memory frame index for a cached entry. Called on cache hits
  * so the extractor's caller receives the same `ExtractedFrames` shape it

package/dist/services/extractionCache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extractionCache.d.ts","sourceRoot":"","sources":["../../src/services/extractionCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,uEAAuE;AACvE,eAAO,MAAM,qBAAqB,WAAW,CAAC;AAE9C,wEAAwE;AACxE,eAAO,MAAM,iBAAiB,iBAAiB,CAAC;AAEhD,oEAAoE;AACpE,eAAO,MAAM,aAAa,gBAAgB,CAAC;AAK3C,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,KAAK,CAAC;AAE7C,MAAM,WAAW,aAAa;IAC5B;+DAC2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,UAAU,EAAE,MAAM,CAAC;IACnB;;yCAEqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,2BAA2B;IAC3B,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED,MAAM,WAAW,UAAU;IACzB,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B;8EAC0E;IAC1E,KAAK,EAAE,UAAU,CAAC;IAClB,sEAAsE;IACtE,GAAG,EAAE,OAAO,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAOvF;AAeD;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAE5D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,WAAW,CAKnF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAE3D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAE9D;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,gBAAgB,CAAC;IACzB,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,aAAa,CAAC;IACxB,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,gBAAgB,GACxB,gBAAgB,CAoBlB"}
+{"version":3,"file":"extractionCache.d.ts","sourceRoot":"","sources":["../../src/services/extractionCache.ts"],"names":[],"mappings":"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"}

package/dist/services/extractionCache.js

@@ -5,7 +5,8 @@
  * after capture. Repeat renders of the same composition (preview → final,
  * studio iteration) re-extract identical frames from the same source file,
  * burning ffmpeg time that adds no value. This module keys extracted frame
- * bundles on the (path, mtime, size, mediaStart, duration, fps, format)
+ * bundles on the (path, mtime, size, mediaStart, duration, fps, format,
+ * optional transform)
  * tuple so re-renders resolve to a pre-extracted directory instead of
  * re-invoking ffmpeg.
  *
@@ -15,10 +16,14 @@
  * - Cache entries live under `<rootDir>/<SCHEMA_PREFIX><key[0..16]>/` so
  *   `ls` output and tracing logs stay short. Truncation to 16 hex chars
  *   leaves 64 bits of entropy — collision risk at cache scale is negligible.
- * - A completed entry is marked by writing the `.hf-complete` sentinel file
- *   after all frames are on disk. A dir without the sentinel is treated as
- *   absent (stale/abandoned) and re-extracted into a fresh key (the old dir
- *   is left for external gc — the cache owns keys, not deletion policy).
+ * - Frames are extracted into a unique `<entry>.partial-<pid>-<uuid>/` dir.
+ *   Once all frames are written, the partial dir receives the `.hf-complete`
+ *   sentinel and is atomically renamed to the final key dir. Concurrent
+ *   same-key writers may duplicate ffmpeg work, but readers only ever serve
+ *   complete entries.
+ * - The sentinel mtime is touched on hits and used as the cache's LRU clock.
+ *   `gcExtractionCache` evicts by that mtime and also clears old partial dirs
+ *   left behind by crashed writers.
  *
  * ### Versioning
  *
@@ -26,16 +31,23 @@
  * extraction format, frame layout). Old entries under the previous prefix
  * become inert and can be gc'd by the caller.
  */
-import { createHash } from "node:crypto";
-import { mkdirSync, readdirSync, statSync, writeFileSync } from "node:fs";
-import { existsSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readdirSync, renameSync, rmSync, statSync, utimesSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
 /** Filename prefix for extracted frames. Shared with the extractor. */
 export const FRAME_FILENAME_PREFIX = "frame_";
 /** Sentinel filename written after a cache entry is fully populated. */
 export const COMPLETE_SENTINEL = ".hf-complete";
-/** Current schema version. Bump when cache-entry layout changes. */
-export const SCHEMA_PREFIX = "hfcache-v2-";
+/** Marker file stamped after each GC sweep; drives the staleness fallback. */
+export const GC_MARKER = ".hf-last-gc";
+/**
+ * Current schema version. Bump when the cache-contents invariant changes.
+ * v2 -> v3: one-pass VFR extraction (-fps_mode cfr) replaces the two-pass
+ * VFR-to-CFR re-encode, changing frame contents for VFR sources under
+ * identical key tuples. Without the bump, warm v2 entries (two-pass frames)
+ * would keep being served across the deploy boundary.
+ */
+export const SCHEMA_PREFIX = "hfcache-v3-";
 /** Truncated hex chars of SHA-256 used for the entry directory name. */
 const KEY_HEX_CHARS = 16;
 /**
@@ -56,7 +68,7 @@ export function readKeyStat(videoPath) {
 }
 function canonicalKeyBlob(input) {
     const durationForKey = Number.isFinite(input.duration) ? input.duration : -1;
-    return JSON.stringify({
+    const blob = {
         p: input.videoPath,
         m: input.mtimeMs,
         s: input.size,
@@ -64,7 +76,10 @@ function canonicalKeyBlob(input) {
         d: durationForKey,
         f: input.fps,
         fmt: input.format,
-    });
+    };
+    if (input.transform !== undefined)
+        blob.t = input.transform;
+    return JSON.stringify(blob);
 }
 /**
  * Compute the SHA-256 hex digest for a cache key input.
@@ -81,9 +96,9 @@ export function cacheEntryDirName(keyHash) {
 }
 /**
  * Look up a cache entry by key input. Returns the resolved entry path plus a
- * `hit` flag. On miss, callers should extract frames into `entry.dir`
- * (after calling `ensureCacheEntryDir`) and then call `markCacheEntryComplete`
- * once the extraction succeeds.
+ * `hit` flag. On miss, callers should extract frames into a
+ * `partialCacheEntryDir(entry)` directory and publish it with
+ * `publishCacheEntry` once extraction succeeds.
  */
 export function lookupCacheEntry(rootDir, input) {
     const keyHash = computeCacheKey(input);
@@ -98,20 +113,237 @@ export function lookupCacheEntry(rootDir, input) {
 export function ensureCacheEntryDir(entry) {
     mkdirSync(entry.dir, { recursive: true });
 }
+/**
+ * Unique render-owned directory used to populate a cache entry before the
+ * atomic publish rename.
+ */
+export function partialCacheEntryDir(entry) {
+    return `${entry.dir}.partial-${process.pid}-${randomUUID().slice(0, 8)}`;
+}
+function isTargetExistsRenameError(err) {
+    const code = err.code;
+    return code === "EEXIST" || code === "ENOTEMPTY" || code === "EPERM";
+}
+/**
+ * Publish an extracted partial directory as the final cache entry.
+ *
+ * Same-filesystem directory rename is atomic: readers either see no entry or
+ * a complete sentineled entry. When another writer wins the race, the caller
+ * should rehydrate from the final dir. If publish cannot complete safely, the
+ * partial remains render-owned and must be cleaned up by the render cleanup.
+ */
+/**
+ * If a concurrent writer's completed entry is visible, discard our partial
+ * and serve theirs. Identical keys produce identical frames, so adopting the
+ * winner is always correct. Returns null when no winner is present.
+ */
+function adoptPublishedWinner(entry, partialDir) {
+    if (!existsSync(join(entry.dir, COMPLETE_SENTINEL)))
+        return null;
+    removeDir(partialDir);
+    return { dir: entry.dir, published: true };
+}
+export function publishCacheEntry(entry, partialDir) {
+    try {
+        writeFileSync(join(partialDir, COMPLETE_SENTINEL), "", "utf-8");
+    }
+    catch {
+        return { dir: partialDir, published: false };
+    }
+    try {
+        renameSync(partialDir, entry.dir);
+        return { dir: entry.dir, published: true };
+    }
+    catch (err) {
+        if (!isTargetExistsRenameError(err))
+            return { dir: partialDir, published: false };
+    }
+    const winner = adoptPublishedWinner(entry, partialDir);
+    if (winner)
+        return winner;
+    try {
+        rmSync(entry.dir, { recursive: true, force: true });
+    }
+    catch {
+        return { dir: partialDir, published: false };
+    }
+    try {
+        renameSync(partialDir, entry.dir);
+        return { dir: entry.dir, published: true };
+    }
+    catch {
+        // TOCTOU: a concurrent writer can publish between the winner check, the
+        // rm above, and this retry. Re-run the adopt check so a winner that
+        // landed inside that window is served rather than reported as a failure.
+        return adoptPublishedWinner(entry, partialDir) ?? { dir: partialDir, published: false };
+    }
+}
+/**
+ * Update the LRU clock for a complete cache entry. Misses and filesystem
+ * races are harmless: the caller can still use the entry it already found.
+ */
+export function touchCacheEntry(entry) {
+    try {
+        const now = new Date();
+        utimesSync(join(entry.dir, COMPLETE_SENTINEL), now, now);
+    }
+    catch {
+        // Best effort LRU touch.
+    }
+}
 /**
  * Write the completion sentinel so subsequent lookups treat this entry as a
- * hit. Must be called only after every frame has been written.
+ * hit. Must be called only after every frame has been written. The extractor
+ * now publishes new entries via `publishCacheEntry`; this helper remains
+ * exported for tests and legacy callers that materialize entries directly.
  *
- * Concurrency: lookup→populate→mark is non-atomic. Two concurrent renders of
- * the same key may both miss, both extract into the same dir, and the later
- * writer's frames win. The result is correct (identical inputs yield identical
- * frames) but wasteful. Acceptable for a single-process render pipeline;
- * anyone running concurrent renders against a shared cache root should front
- * it with an external lock.
+ * Concurrency: direct mark is non-atomic and should not be used for shared
+ * writer paths. `publishCacheEntry` writes the sentinel inside a partial dir
+ * and atomically renames it into place, so concurrent writers duplicate work
+ * but never serve torn frames.
  */
 export function markCacheEntryComplete(entry) {
     writeFileSync(join(entry.dir, COMPLETE_SENTINEL), "", "utf-8");
 }
+/** Any generation of this cache's entries ("hfcache-v*"), current or superseded. */
+const CACHE_GENERATION_PREFIX = "hfcache-v";
+function isCacheLikeChild(name) {
+    // Match every schema generation, not just SCHEMA_PREFIX: after a schema
+    // bump, superseded-version entries would otherwise be invisible to the
+    // sweep and orphan their disk forever. Old-generation entries never get
+    // sentinel touches, so the LRU evicts them first.
+    return name.startsWith(CACHE_GENERATION_PREFIX) || name.includes(".partial-");
+}
+function isPartialChild(name) {
+    return name.includes(".partial-");
+}
+function directorySizeBytes(path) {
+    try {
+        const stat = lstatSync(path);
+        if (!stat.isDirectory())
+            return stat.size;
+    }
+    catch {
+        return 0;
+    }
+    let total = 0;
+    let children;
+    try {
+        children = readdirSync(path);
+    }
+    catch {
+        return 0;
+    }
+    for (const child of children) {
+        const childPath = join(path, child);
+        try {
+            const stat = lstatSync(childPath);
+            if (stat.isDirectory()) {
+                total += directorySizeBytes(childPath);
+            }
+            else {
+                total += stat.size;
+            }
+        }
+        catch {
+            // Ignore entries deleted or made unreadable during the sweep.
+        }
+    }
+    return total;
+}
+function removeDir(path) {
+    try {
+        rmSync(path, { recursive: true, force: true });
+    }
+    catch {
+        // Cache GC is opportunistic; one bad entry must not abort the sweep.
+    }
+}
+/**
+ * Stat one cache-looking child for the GC sweep. Aged partial dirs (crashed
+ * writers) are removed immediately and yield `null`; entries that disappear
+ * or fail to stat mid-sweep also yield `null`.
+ */
+function collectGcEntry(dir, name, now, minAgeMs, stats) {
+    try {
+        const dirStat = statSync(dir);
+        if (isPartialChild(name) && now - dirStat.mtimeMs >= minAgeMs) {
+            removeDir(dir);
+            stats.agedPartialsRemoved += 1;
+            return null;
+        }
+        let lastUseMs = dirStat.mtimeMs;
+        try {
+            lastUseMs = statSync(join(dir, COMPLETE_SENTINEL)).mtimeMs;
+        }
+        catch {
+            // Unsentineled entries use directory mtime as a stale-entry clock.
+        }
+        return { dir, size: directorySizeBytes(dir), lastUseMs, ageMs: now - lastUseMs };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Opportunistic size-capped LRU cleanup for extracted video frames.
+ *
+ * Scans only direct cache-looking children and never throws. The age guard is
+ * a liveness heuristic, not a lock. Returns counts so the caller can surface
+ * eviction pressure in render observability.
+ */
+/**
+ * Whether the staleness fallback should force a sweep: true when no sweep
+ * marker exists or the last sweep is older than `maxAgeMs`. Lets 100%-warm
+ * workloads (which skip the per-miss sweep) still reclaim space eventually.
+ */
+export function gcSweepDue(rootDir, maxAgeMs) {
+    try {
+        return Date.now() - statSync(join(rootDir, GC_MARKER)).mtimeMs > maxAgeMs;
+    }
+    catch {
+        return true;
+    }
+}
+export function gcExtractionCache(rootDir, opts) {
+    const stats = { evictedEntries: 0, evictedBytes: 0, agedPartialsRemoved: 0 };
+    try {
+        writeFileSync(join(rootDir, GC_MARKER), "", "utf-8");
+    }
+    catch {
+        // Unwritable root: the sweep below will no-op on the same root anyway.
+    }
+    try {
+        const now = Date.now();
+        const entries = [];
+        for (const child of readdirSync(rootDir, { withFileTypes: true })) {
+            if (!child.isDirectory() || !isCacheLikeChild(child.name))
+                continue;
+            const entry = collectGcEntry(join(rootDir, child.name), child.name, now, opts.minAgeMs, stats);
+            if (entry)
+                entries.push(entry);
+        }
+        let totalBytes = entries.reduce((sum, e) => sum + e.size, 0);
+        if (totalBytes <= opts.maxBytes)
+            return stats;
+        entries.sort((a, b) => a.lastUseMs - b.lastUseMs);
+        for (const entry of entries) {
+            // ponytail: age-based liveness guard, not a lock; a render longer than minAge with a full cache could lose entries mid-read - acceptable, next render re-extracts.
+            if (entry.ageMs < opts.minAgeMs)
+                continue;
+            removeDir(entry.dir);
+            stats.evictedEntries += 1;
+            stats.evictedBytes += entry.size;
+            totalBytes -= entry.size;
+            if (totalBytes <= opts.maxBytes)
+                break;
+        }
+    }
+    catch {
+        // Missing root or unreadable cache: no cleanup this sweep.
+    }
+    return stats;
+}
 export function rehydrateCacheEntry(entry, options) {
     const framePattern = `${FRAME_FILENAME_PREFIX}%05d.${options.format}`;
     const framePaths = new Map();