Fetch the dataset's validation token directly from the server, bypassing
every cache tier. Used by validation to detect server-side dataset
changes. Uses the dedicated validationTimeoutMs budget so a flaky
network does not block scene loading for the full data-fetch timeout.
When the root metadata carries Luxar's content_hash attr, that is the
token (content-hash mode — strongest guarantee). Otherwise the SHA-256
of the raw document bytes serves as an implicit token (zattrs-hash
mode): every Luxar writer re-stamps a per-save timestamp attr and most
external producers rewrite root metadata on regeneration, so a dataset
replaced in place at the same URL still invalidates instead of being
served stale from OPFS forever (the pre-fix behaviour with the default
externalDatasetTtlMs: null).
BOTH formats' documents are tried, zarr.json first. Probing only .zattrs
— correct while every store was format 2 — returns null for a format-3
dataset, which drops the caller onto the TTL path and reinstates exactly the
serve-stale-forever behaviour this function exists to prevent. The
zattrs-hash mode name is kept for a format-3 document too: it is a stable
identifier that callers and tests match on, and renaming it to suit the
format would break them to describe the same thing.
timeoutMsOverride stays a budget for the WHOLE probe, not per candidate:
with two sequential fetches a hanging server would otherwise block scene
loading for twice the fail-fast budget the option exists to impose, and it is
a format-2 dataset — the one that needs the second request — that would pay
it. The first candidate keeps the full budget, so the common single-request
case is unchanged.
Returns null only if NEITHER document can be fetched or both are non-ok
(offline / truly headerless store) — callers then fall back to the TTL path.
Fetch the dataset's validation token directly from the server, bypassing every cache tier. Used by validation to detect server-side dataset changes. Uses the dedicated
validationTimeoutMsbudget so a flaky network does not block scene loading for the full data-fetch timeout.When the root metadata carries Luxar's
content_hashattr, that is the token (content-hashmode — strongest guarantee). Otherwise the SHA-256 of the raw document bytes serves as an implicit token (zattrs-hashmode): every Luxar writer re-stamps a per-savetimestampattr and most external producers rewrite root metadata on regeneration, so a dataset replaced in place at the same URL still invalidates instead of being served stale from OPFS forever (the pre-fix behaviour with the defaultexternalDatasetTtlMs: null).BOTH formats' documents are tried,
zarr.jsonfirst. Probing only.zattrs— correct while every store was format 2 — returnsnullfor a format-3 dataset, which drops the caller onto the TTL path and reinstates exactly the serve-stale-forever behaviour this function exists to prevent. Thezattrs-hashmode name is kept for a format-3 document too: it is a stable identifier that callers and tests match on, and renaming it to suit the format would break them to describe the same thing.timeoutMsOverridestays a budget for the WHOLE probe, not per candidate: with two sequential fetches a hanging server would otherwise block scene loading for twice the fail-fast budget the option exists to impose, and it is a format-2 dataset — the one that needs the second request — that would pay it. The first candidate keeps the full budget, so the common single-request case is unchanged.Returns
nullonly if NEITHER document can be fetched or both are non-ok (offline / truly headerless store) — callers then fall back to the TTL path.