@@ -392,24 +392,60 @@ tombstones can be reclaimed.
 With the flag on, completed image-filter outputs are uploaded to the `generated-assets` group as
 they are produced, at `generated-assets/{first}/{second}/{inode}/dotGenerated_...`, with the same
 relative layout under the local `dotGenerated` root. A cold read restores a completed rendition
-from S3 without running the filter again. Warm hits do not contact S3, so an S3 outage does not
-break a cached response and a warm read cannot republish an invalidated object. Incomplete filter
-outputs are never uploaded or evicted. Thumbnail invalidation and source deletion target that
-inode's directory. With the flag off, renditions keep the existing two-character layout. Existing
-rendition objects are not moved to the new layout.
+from S3 without running the filter again. A warm hit is served from local disk without contacting
+S3, so an S3 outage does not break a cached response and a warm read cannot republish an
+invalidated object. A cold read, which has to look in S3, fails while S3 is unavailable.
+Incomplete filter outputs are never uploaded or evicted. Thumbnail invalidation and source
+deletion target that inode's directory. With the flag off, renditions keep the existing
+two-character layout. Existing rendition objects are not moved to the new layout.
+
+The exporter finds an existing rendition by predicting the path each filter writes, so each
+filter's prediction must match its output; the JPEG filter, for example, predicts `.jpg`. Some
+requests leave the image unchanged, for instance a maximum width larger than the image. Such a
+filter writes nothing, so the first request for it looks for its predicted output in S3 and finds
+nothing. The node then remembers that this output is never produced, and later requests on that
+node skip the lookup. Only an output written at its predicted path is uploaded.
+
+Upload failures do not fail the request. If S3 rejects a rendition upload, the locally produced
+rendition is served and a warning is logged. The rendition then stays local only: later requests
+on that node are warm hits and do not retry the upload, eviction keeps the file because it has no
+durable copy, and other nodes generate their own. Uploads run after the image-generation permit is
+released.
 
 Rendition keys include the original's revision key, so replacing bytes under the same inode and
 filename never selects the previous revision's rendition. Crops read the focal point from the
 content's metadata snapshot, including focal points saved on a temporary upload, and the Java and
-native crop engines use the same pinned coordinates. Image-filter execution holds a cache lease
-while it reads the original.
+native crop engines use the same pinned coordinates. When a focal point is read through the
+content API instead, as `$content.image.fpx` does, content the current user cannot read, or that
+does not exist, has no focal point, as with the flag off; only a failed lookup is an error.
 
 Compiled Sass output also uses the `generated-assets` group. Its key covers the source and
 dependency bytes, site, live or working mode, compiler options and application build, so a cold
 node restores a matching CSS output without running Sass. Source maps keep their existing private,
-uncached behavior. Markdown files are read through the protected FileAsset stream, and VTL and
-included files are opened through the binary asset API, so a file whose local copy was evicted is
-restored from S3 before it is rendered.
+uncached behavior. As with renditions, a compiled output whose upload fails is still served,
+with a warning, and is kept locally only. Each change to the key, such as an edit to an imported
+partial, a working-mode compile of an edit in progress, or an upgrade, stores a new CSS object
+without removing the old one. Old objects are removed only when the main Sass file's generated
+outputs are invalidated or its inode's binaries are deleted, so for a main file that rarely
+changes they accumulate. Superseded compiled CSS objects are not reclaimed yet.
+
+Markdown files are read through the protected FileAsset stream, and VTL and included files are
+opened through the binary asset API, so a file whose local copy was evicted is restored from S3
+before it is rendered. A missing VTL or included file outside the asset root cannot be restored,
+so it is reported as not found, as with the flag off. When restoring a VTL, macro or included file
+fails, the render fails with a storage error that is not cached as a missing template, so the next
+render tries again. Templates, containers, pages and other database-built sources keep their
+existing failure handling.
+
+### Known limitation: long cache leases
+
+Image-filter execution holds a cache lease for the whole export: the S3 lookups, the pixel work
+and the uploads of every filter in the chain. Sass compilation holds a lease while it gathers and
+copies the sources, which includes database lookups, and while it reads a stored output, but not
+while Dart Sass runs. Eviction skips every file while any lease is held, so on a node with steady
+image traffic a sweep can be deferred again and again, and the local cache can stay above its
+budget. Narrowing the rendition lease to the moments a filter reads a local file needs the filters
+to restore their inputs themselves, which is a larger change and is left as a follow-up.
 
 ## Local cache eviction
 
@@ -509,7 +545,7 @@ docker run -d --rm --name binary-cleanup-postgres-test \
   -e POSTGRES_DB=binary_storage_test postgres:16-alpine
 
 ./mvnw test -pl :dotcms-core -Dmaven.build.cache.enabled=false \
-  -Dtest=AssetStorageFeatureTest,AssetStorageFeatureLatchTest,S3StorageConfigurationTest,NoWebIdentityCredentialsProviderChainTest,BinaryS3StorageTest,BinaryAssetReferenceTest,BinaryCacheEvictionJobTest,BinaryFileSystemStorageTest,BinaryAssetStorageAPIImplTest,MetadataLocalCacheTest,BinaryAssetCleanupTransactionTest,BinaryAssetCleanupProcessorTest,ContentletBackupStorageGateTest,BinaryFieldCleanupProcessorTest,AssetJobEventSerializationTest,BinaryAssetBackfillCheckpointTest,ImportStarterWorkflowCleanupTest,BinaryAssetBackfillProcessorTest,BinaryAssetBackfillTest,ExportStarterFailureTest,BundleArchiveStorageTest,FileAssetBundlerTest,TemporaryAssetStorageTest,WebdavAssetStorageTest,TemporaryMetadataStorageTest,WebdavTemporaryStorageTest,ImageFilterExporterFocalPointTest,ImageFilterExporterTest,ImageFilterExporterSharedStoreTest,ImageFilterExporterEngineSelectionTest \
+  -Dtest=AssetStorageFeatureTest,AssetStorageFeatureLatchTest,S3StorageConfigurationTest,NoWebIdentityCredentialsProviderChainTest,BinaryS3StorageTest,BinaryAssetReferenceTest,BinaryCacheEvictionJobTest,BinaryFileSystemStorageTest,BinaryAssetStorageAPIImplTest,MetadataLocalCacheTest,BinaryAssetCleanupTransactionTest,BinaryAssetCleanupProcessorTest,ContentletBackupStorageGateTest,BinaryFieldCleanupProcessorTest,AssetJobEventSerializationTest,BinaryAssetBackfillCheckpointTest,ImportStarterWorkflowCleanupTest,BinaryAssetBackfillProcessorTest,BinaryAssetBackfillTest,ExportStarterFailureTest,BundleArchiveStorageTest,FileAssetBundlerTest,TemporaryAssetStorageTest,WebdavAssetStorageTest,TemporaryMetadataStorageTest,WebdavTemporaryStorageTest,ImageFilterExporterFocalPointTest,ImageFilterExporterTest,ImageFilterExporterSharedStoreTest,ImageFilterExporterEngineSelectionTest,ImageFilterExporterStorageTest,FocalPointAPIImplTest,StoredVelocityFileLoaderTest \
   -Ds3.test.endpoint=http://127.0.0.1:19002 \
   -Ds3.test.jdbc=jdbc:postgresql://127.0.0.1:19003/binary_storage_test
 
 
@@ -62,20 +62,23 @@ public DotLibSassCompiler(final Host host, final String uri, final boolean live,
         this.sourceMap = sourceMap;
     }
 
+    /**
+     * Compiles the SCSS or Sass file into {@link #getOutput()}.
+     *
+     * <p>With S3 asset storage on, a compiled CSS output stored under a key that covers the source
+     * bytes, site, mode, options and build is reused, locally or restored from S3, without running
+     * Dart Sass. A new output is written locally and uploaded. If storing it fails, the compiled
+     * CSS is still returned and a warning is logged. A cache lease is held only while the sources
+     * are copied and while a stored output is read, not while Dart Sass runs.
+     *
+     * @throws DotSecurityException if a source cannot be read by the system user
+     * @throws DotStateException if the dotCMS state is inconsistent
+     * @throws DotDataException if a source or its version information cannot be loaded
+     * @throws IOException if the compile directory cannot be prepared
+     */
     @Override
     public void compile() throws DotSecurityException, DotStateException, DotDataException, IOException {
 
-        if (com.dotcms.storage.AssetStorageFeature.isEnabled()) {
-            try (var lease = APILocator.getBinaryAssetStorageAPI().acquireCacheLease()) {
-                compileInternal();
-            }
-        } else {
-            compileInternal();
-        }
-    }
-
-    private void compileInternal() throws DotSecurityException, DotDataException, IOException {
-
         String trying = inputURI.substring(0, inputURI.lastIndexOf('.')) + "." + getDefaultExtension();
         final File compileDir  = createCompileDir( inputHost, trying, inputLive );
 
@@ -119,18 +122,26 @@ private void compileInternal() throws DotSecurityException, DotDataException, IO
             final File storedCSS = com.dotcms.storage.AssetStorageFeature.isEnabled() && !sourceMap
                     ? compiledCacheFile(mainFile.getInode(), options) : null;
             if (storedCSS != null) {
-                final File cached = APILocator.getBinaryAssetStorageAPI().getGeneratedFile(storedCSS);
-                if (cached != null && (req == null || req.getParameter("recompile") == null)) {
-                    this.output = java.nio.file.Files.readAllBytes(cached.toPath());
-                    return;
+                try (var lease = APILocator.getBinaryAssetStorageAPI().acquireCacheLease()) {
+                    final File cached = APILocator.getBinaryAssetStorageAPI().getGeneratedFile(storedCSS);
+                    if (cached != null && (req == null || req.getParameter("recompile") == null)) {
+                        this.output = java.nio.file.Files.readAllBytes(cached.toPath());
+                        return;
+                    }
                 }
             }
             final DartSassCompiler compiler = new DartSassCompiler(options, compileTargetFile, compileDestinationFile);
             final Optional<String> out = compiler.compile();
             handleOutput(compiler.terminalOutput());
             this.output = out.isPresent() ? out.get().getBytes() : null;
             if (storedCSS != null && this.output != null && compiler.terminalOutput().exitValue() == 0) {
-                storeCompiledOutput(storedCSS);
+                try {
+                    storeCompiledOutput(storedCSS);
+                } catch (final Exception e) {
+                    // Availability first: the CSS is compiled, so a storage failure must not fail the request.
+                    Logger.warnAndDebug(DotLibSassCompiler.class, "Unable to store compiled CSS for " + inputHost
+                            + ":" + inputURI + "; serving the compiled output: " + e.getMessage(), e);
+                }
             }
         } catch (final Exception ex) {
             final String errorMsg = String.format("Unable to compile SASS code in %s:%s [ live:%s ]: %s", inputHost,
@@ -158,6 +169,15 @@ private File compiledCacheFile(final String inode, final CompilerOptions options
                 inode.charAt(0) + "/" + inode.charAt(1) + "/" + inode + "/dotGenerated_css_" + hash + ".css");
     }
 
+    /**
+     * Writes the compiled CSS atomically to its local {@code dotGenerated} path and uploads it.
+     * If the upload fails, the local file is kept: later requests on this node serve it, and
+     * eviction never removes it because it has no durable copy.
+     *
+     * @param target the local path of the compiled CSS
+     * @throws IOException if the local file cannot be written
+     * @throws DotDataException if the upload fails
+     */
     private void storeCompiledOutput(final File target) throws IOException, DotDataException {
         final java.nio.file.Path path = target.toPath();
         java.nio.file.Files.createDirectories(path.getParent());
@@ -170,17 +190,7 @@ private void storeCompiledOutput(final File target) throws IOException, DotDataE
             } catch (java.nio.file.AtomicMoveNotSupportedException e) {
                 java.nio.file.Files.move(temporary, path, java.nio.file.StandardCopyOption.REPLACE_EXISTING);
             }
-            try {
-                APILocator.getBinaryAssetStorageAPI().storeGeneratedFile(target);
-            } catch (DotDataException e) {
-                // Failed publication must not leave a warm-only result that is never uploaded on retry.
-                try {
-                    java.nio.file.Files.deleteIfExists(path);
-                } catch (IOException cleanup) {
-                    e.addSuppressed(cleanup);
-                }
-                throw e;
-            }
+            APILocator.getBinaryAssetStorageAPI().storeGeneratedFile(target);
         } finally {
             java.nio.file.Files.deleteIfExists(temporary);
         }
 
@@ -2,12 +2,14 @@
 
 
 import com.dotmarketing.business.CacheLocator;
+import com.dotmarketing.exception.DotDataException;
 import com.dotmarketing.util.Config;
 import com.dotmarketing.util.Logger;
 import com.dotmarketing.util.UtilMethods;
 import java.io.InputStream;
 import org.apache.commons.collections.ExtendedProperties;
 import org.apache.velocity.exception.ResourceNotFoundException;
+import org.apache.velocity.exception.VelocityException;
 import org.apache.velocity.runtime.resource.Resource;
 import org.apache.velocity.runtime.resource.loader.ResourceLoader;
 
@@ -22,6 +24,19 @@ public DotResourceLoader() {
     }
 
 
+    /**
+     * Opens the Velocity source for a resource path, choosing the loader by the path's type.
+     *
+     * <p>A failure normally records a cache miss and is reported as a
+     * {@link ResourceNotFoundException}. With S3 asset storage on, a {@link DotDataException}
+     * from a loader that reads a stored file (VTL, macro, legacy VL and include files) means the
+     * file could not be restored from storage. It is reported as a plain {@link VelocityException}
+     * and no miss is recorded, so the next render tries the storage again.
+     *
+     * @param filePath the Velocity resource path
+     * @return the resource source
+     * @throws ResourceNotFoundException if the path is empty or the resource cannot be loaded
+     */
     @Override
     public InputStream getResourceStream(final String filePath) throws ResourceNotFoundException {
         if (!UtilMethods.isSet(filePath)) {
@@ -76,8 +91,8 @@ public InputStream getResourceStream(final String filePath) throws ResourceNotFo
             } catch (Exception e) {
                 Logger.warn(this, "filePath: " + filePath + ", msg:" + e.getMessage(), e);
                 if (com.dotcms.storage.AssetStorageFeature.isEnabled()
-                        && e instanceof com.dotmarketing.exception.DotDataException) {
-                    throw new org.apache.velocity.exception.VelocityException("Unable to load stored resource: " + key.path, e);
+                        && e instanceof DotDataException && readsStoredFile(key.type)) {
+                    throw new VelocityException("Unable to load stored resource: " + key.path, e);
                 }
                 CacheLocator.getVeloctyResourceCache().addMiss(key.path);
                 throw new ResourceNotFoundException("Cannot parse velocity file : " + key.path, e);
@@ -86,6 +101,29 @@ public InputStream getResourceStream(final String filePath) throws ResourceNotFo
 
     }
 
+    /**
+     * Tells whether a resource type is loaded from a file that S3 asset storage may have to
+     * restore. These are the types {@link #getResourceStream} hands to {@link VTLLoader} and
+     * {@link IncludeLoader}; the other loaders build their source from the database.
+     *
+     * @param type the resource type
+     * @return {@code true} for VTL, macro, legacy VL and include files
+     */
+    private static boolean readsStoredFile(final VelocityType type) {
+        switch (type) {
+            case CONTAINER:
+            case TEMPLATE:
+            case CONTENT:
+            case FIELD:
+            case CONTENT_TYPE:
+            case SITE:
+            case HTMLPAGE:
+                return false;
+            default:
+                return true;
+        }
+    }
+
     /*
      * (non-Javadoc)
      * 
 
@@ -58,10 +58,24 @@ private Set<String> buildAllowedExtensions() {
     }
 
 
+    /**
+     * Checks that an included file may be served: it must be under the Velocity root or the asset
+     * root and have an allowed extension.
+     *
+     * <p>With S3 asset storage on, a missing file under the asset root passes this check so that
+     * it can be restored from storage. A missing file anywhere else is reported as not found, as
+     * with the flag off, rather than logged as a possible attack.
+     *
+     * @param filePath the file path from the Velocity resource key
+     * @return the file to serve
+     * @throws IOException if a canonical path cannot be resolved
+     * @throws ResourceNotFoundException if the file is missing or not allowed
+     */
     private File allowedToServe(final String filePath) throws IOException {
         final File fileToServe = new File(filePath);
         final boolean s3 = com.dotcms.storage.AssetStorageFeature.isEnabled();
-        if (!fileToServe.exists() && !s3) {
+        if (!fileToServe.exists()
+                && (!s3 || !fileToServe.getCanonicalFile().toPath().startsWith(allowedPaths[1]))) {
             throw new ResourceNotFoundException(CANNOT_FIND_RESOURCE + filePath);
         }
         String canonicalPath = fileToServe.getCanonicalPath();
 
@@ -80,6 +80,34 @@ private void init() {
 
     }
 
+    /**
+     * Tells whether a file is under the asset root, the only place S3 asset storage can restore
+     * a missing file from.
+     *
+     * @param file the file to check
+     * @return {@code true} if its canonical path is under the canonical asset root
+     * @throws IOException if a canonical path cannot be resolved
+     */
+    private static boolean underAssetRoot(final File file) throws IOException {
+        final String assetRoot = ConfigUtils.getAssetPath();
+        return UtilMethods.isSet(assetRoot) && file.getCanonicalFile().toPath()
+                .startsWith(new File(assetRoot).getCanonicalFile().toPath());
+    }
+
+    /**
+     * Opens a VTL, macro or legacy VL file from the Velocity root, the dynamic content path or
+     * the asset directories, refusing paths outside them.
+     *
+     * <p>With S3 asset storage on, the file is opened through the binary asset API, so a file
+     * whose local copy was evicted is restored first. A missing file outside the asset root
+     * cannot be restored and is reported as not found, as with the flag off.
+     *
+     * @param filePath the file path from the Velocity resource key
+     * @return the file contents
+     * @throws IOException if the file cannot be read
+     * @throws DotDataException if restoring the file from storage fails
+     * @throws ResourceNotFoundException if the file is missing or outside the allowed roots
+     */
     InputStream streamFile(String filePath) throws IOException, DotDataException {
         final boolean s3 = com.dotcms.storage.AssetStorageFeature.isEnabled();
         boolean serveFile = false;
@@ -97,7 +125,8 @@ InputStream streamFile(String filePath) throws IOException, DotDataException {
         if (!f.exists()) {
             f = new java.io.File(filePath);
         }
-        if (!f.exists() && !s3) {
+        // A missing file can only be restored from storage when it is under the asset root.
+        if (!f.exists() && (!s3 || !underAssetRoot(f))) {
             throw new ResourceNotFoundException("cannot find resource");
         }
         String canon = f.getCanonicalPath();