Surviving a Core Upgrade

const VERSION_STEPS  = ['download', 'extract', 'database', 'configuration', 'apply'];
const PREIMAGE_DIR   = 'updates-preimage';   // under coremio/storage/
const PREIMAGE_KEEP  = 3;                    // runs retained, pruned when a new run opens
const LINT_SECONDS   = 60.0;                 // gate lint budget, time not file count
const LINT_MAX_FILES = 2000;                 // safety brake behind the time budget
const HTTP_SETTLE_SECONDS = 5;               // waited before asking, and after restoring

public static function open(array $opts, string $workerId): int;
public static function tick(int $runId, string $workerId): array;
public static function health_probe(): array;
public static function restorable(): array;
public static function restore_last(): array;
public static function parked(array $run): bool;

public static function check_state(): array;
public static function check_new_version(): array;
public static function next_versions(string|int $ver = 0): array;
public static function run_active(string $kind = 'core'): array;
public static function last_completed_run(string $kind = 'core'): array;
public static function run_get(int $id): array;
public static function sc_state(): array;

// coremio/helpers/license.php - what the installation currently claims to be.
public static function version($realtime = false): string;

{"type":"marketplace","name":"AcmeBilling","version":"1.2.0","last_updated":"2026-07-28"}

namespace WISECP\Modules\Addons\Acme\Src;

class Compat
{
    // The dependency surface, as data. Everything this module touches outside its
    // own directory is listed here, so the probe is the list and not a rewrite.
    private const NEEDS_METHOD = [
        'Checkout::payment_methods',
        'Services::get',
        'Invoices::create',
    ];

    private const NEEDS_HOOK = [
        'filter:order.cart_totals',
        'action:order.checkout_completed',
    ];

    private const CORE_MIN = '5.0.0';
    private const CORE_MAX = '6.0.0';   // exclusive: a major bump is opt-in, never assumed

    /** @return array{ok:bool,errors:string[],skipped:string[],version:string} */
    public static function check(): array
    {
        $errors = $skipped = [];
        $core   = \License::version();

        if (version_compare($core, self::CORE_MIN, '<'))
            $errors[] = 'core ' . $core . ' is below the minimum ' . self::CORE_MIN;

        if (version_compare($core, self::CORE_MAX, '>='))
            $skipped[] = 'core ' . $core . ' is newer than this module was tested against';

        foreach (self::NEEDS_METHOD as $ref) {
            [$class, $method] = explode('::', $ref, 2);
            if (!class_exists($class))            $errors[] = 'missing class: ' . $class;
            elseif (!method_exists($class, $method)) $errors[] = 'missing method: ' . $ref;
        }

        // A capability, not a result. Under FPM these are usually disabled while the
        // same server's CLI keeps them, so "cannot ask" must never read as "failed".
        if (!function_exists('exec')) $skipped[] = 'subprocess probes (exec unavailable)';

        foreach (self::NEEDS_HOOK as $hook)
            if (!self::hook_seen($hook)) $skipped[] = 'hook not observed yet: ' . $hook;

        return ['ok' => !$errors, 'errors' => $errors, 'skipped' => $skipped, 'version' => $core];
    }

    /*
     * There is no runtime registry of hook NAMES: hooks are fired, not declared, and the
     * store is private. So the only honest answer is observational - the canary below
     * records a timestamp when the point actually fires, and "not seen" is skipped,
     * never an error, because it may simply not have been reached yet.
     */
    public static function canary(string $hook): void
    {
        $seen = (array) \Utility::jdecode((string) \Config::getd('acme_hook_seen'), true);
        $seen[$hook] = time();

        \Config::setd('acme_hook_seen', \Utility::jencode($seen));
    }

    private static function hook_seen(string $hook): bool
    {
        $seen = (array) \Utility::jdecode((string) \Config::getd('acme_hook_seen'), true);

        return (int) ($seen[$hook] ?? 0) > 0;
    }
}

use WISECP\Modules\Addons\Acme\Src\Compat;

include_once __DIR__ . DS . 'src' . DS . 'Compat.php';

// Priority 1: ahead of the real listener, so the observation is independent of it.
Hook::add('filter:order.cart_totals', 1, function (&$summary, $items, $subtotal) {
    Compat::canary('filter:order.cart_totals');
});

// The gate the module itself sits behind. An incompatible core disables the feature
// instead of throwing inside somebody's checkout.
$acme_compat = Compat::check();

if ($acme_compat['ok']) {
    Hook::add('filter:order.cart_totals', 20, function (&$summary, $items, $subtotal) {
        // ... the real work
    });
}
else {
    Hook::add('ui:admin.body.end', 90, function () use ($acme_compat) {
        return '<!-- acme disabled: ' . htmlspecialchars(implode('; ', $acme_compat['errors'])) . ' -->';
    });
}

# What the gate actually saw, including everything it could not measure.
cat coremio/storage/updates-preimage/*/gate.json

# Errors since the run, where a swallowed listener exception is the only trace.
php coremio/errlog.php list --limit=20