How JSON cache entries are generated

POM Cache does not invent the progressive archive response. POM Theme renders the batch, decides whether it is reusable, and hands the finished JSON to POM Cache for storage.

This boundary is important when diagnosing an empty cache: a write can happen only after the theme has generated a valid, cacheable response.

Generation sequence

For a clean request that has no usable stored file:

POM Theme resolves archive context
→ validates URL hash and items-per-page
→ queries requested batch
→ renders archive item HTML
→ builds pagination and next-URL data
→ marks response cacheable or dynamic
→ encodes valid JSON
→ POM Cache validates and writes
→ visitor receives the generated response

POM Cache writes only the final encoded representation. The file therefore contains the same archive payload delivered to the visitor, including rendered item fragments where the progressive component expects them.

Conditions required for a write

A file is stored only when:

• Progressive JSON cache is Enabled;
• JSON writes is Enabled;
• POM Theme marks the response as cacheable;
• the route's context hash and items-per-page match current settings;
• the cache-relative path passes validation and ends in .json;
• the encoded response is not empty;
• its byte length does not exceed Maximum JSON file size;
• the response decodes as valid JSON;
• the destination directory exists or can be created and is writable;
• no supported extension vetoes the write.

Failure at any one of these checks leaves the dynamic response available to the current visitor but does not create a cache entry.

What the status header tells you

On the dynamic WordPress path, POM Theme can return:

X-POM-Progressive-Archive-Cache: generated-cacheable

This confirms the route was eligible; it does not by itself prove the file write succeeded. Check Progressive JSON Cache Contents before and after the request, then repeat the URL and look for a hit.

By contrast:

X-POM-Progressive-Archive-Cache: generated-dynamic

means the response was intentionally not treated as reusable. Enabling file permissions or increasing the size setting will not change that classification.

On-demand, not preloaded

POM Cache creates only batches that visitors or a deliberate verification request actually request. It does not crawl:

• every archive;
• every page number;
• every taxonomy section;
• every locale;
• every posts-per-page combination.

As a result, the cache grows according to real navigation. A three-language archive with ten possible batches does not create thirty files at activation; only requested combinations appear.

After a clear, each required combination must be generated again on its first request.

Safe file replacement

When a valid entry is ready, POM Cache writes to a temporary file in the destination directory and then moves that complete file into place. This reduces the chance that two visitors see partially written JSON.

The path is constrained below the current site's JSON namespace. Unsafe traversal patterns, malformed segments, and extensions other than .json are refused.

These safeguards do not make the cache a source of truth. It remains generated output that can be deleted at any time.

Changes that create a new context path

The public URL includes an archive context hash and the items-per-page value. A meaningful archive configuration change can therefore produce a new URL and new directory instead of overwriting an old context.

That protects visitors from receiving a structurally incompatible response, but it also means old files can remain until you clear them. After changing progressive archive templates, batch size, grouping, or other global display behavior:

1. Clear the progressive JSON cache;
2. Request representative archives in each locale;
3. Verify the new URLs and payloads;
4. Clear or invalidate matching CDN paths where necessary.

Do not rely on the new hash alone as a storage cleanup strategy.

First-generation verification

1. Open POM Cache → General → Progressive JSON tools and note the current file count.
2. Use Delete Progressive JSON Cache for a clean test.
3. Open a progressive archive as a logged-out visitor.
4. Trigger one later batch;
5. Inspect the JSON request for generated-cacheable;
6. Refresh the tools view and confirm the count increased;
7. Repeat the exact URL and confirm an early or WordPress hit;
8. Edit a source item, run the appropriate invalidation, and confirm regeneration returns the changed content.

If step 5 succeeds but step 6 does not, focus on JSON writes, maximum size, and filesystem permissions. If step 5 reports generated-dynamic, focus on the archive context and request shape.

See Monitor JSON cache size for growth behavior and Understand JSON cache files for the resulting layout.