Integrate progressive JSON writes

pom_cache_json_write() stores one application-owned JSON payload in the current site's progressive JSON tree. It returns true only after an eligible payload is written successfully.

Write a payload

$relative_path = 'archive/book/page-2.json';
$payload = array(
    'items' => $public_items,
    'page'  => 2,
);
$json = wp_json_encode( $payload );

if (
    false !== $json
    && function_exists( 'pom_cache_json_write' )
) {
    $written = pom_cache_json_write(
        $relative_path,
        $json,
        array(
            'integration' => 'my_catalog',
            'post_type'   => 'book',
            'cacheable'   => true,
        )
    );
}

The helper requires:

• the progressive JSON master switch;
• JSON writes enabled;
• a safe normalized .json relative path;
• a non-empty JSON string within the configured maximum size;
• valid JSON;
• an allowed pom_cache_json_should_write decision;
• a writable destination.

It creates missing directories, writes through a temporary file with a lock, and moves that file into place. Do not write directly to the final cache path.

Veto a write

add_filter(
    'pom_cache_json_should_write',
    static function ( $should_write, $relative_path, $json, $context ) {
        unset( $relative_path, $json );

        if ( ! $should_write ) {
            return false;
        }

        return ! empty( $context['cacheable'] );
    },
    10,
    4
);

The filter decides whether to store; it does not modify the JSON. Put stable facts such as post type, locale, and integration name into the context. Never put secrets there because other callbacks can inspect the array.

Observe writes

POM Cache emits:

add_action(
    'pom_cache_json_before_write',
    static function ( $file, $json, $context ) {
        // Lightweight observation before the temporary write.
    },
    10,
    3
);

add_action(
    'pom_cache_json_after_write',
    static function ( $file, $json, $context ) {
        // The final file has been moved into place.
    },
    10,
    3
);

The before action can run even if a later filesystem operation fails. The after action is the completion signal. Keep both callbacks fast; do not log the entire payload when it may contain personal or commercially sensitive data.

POM Theme generation contract

POM Cache listens to:

do_action(
    'pom_progressive_archive_json_generated',
    $relative_path,
    $json,
    $response,
    $context
);

It writes only when $context['cacheable'] is truthy. A generator must decide cacheability from public response semantics, not merely from a successful HTTP status.

Key design

Every public variation must map to a distinct deterministic relative path. Include locale, post type, pagination, and public filter state when they change the payload. Exclude user ID, nonce, session, or secret parameters entirely; such payloads should remain dynamic.

After changing the key format, purge the old current-site JSON tree or explicitly retire obsolete paths. POM Cache cannot infer that two different relative paths represent successive versions of the same logical response.