@honua/app-platform 0.1.11-beta.0 → 0.1.13

package/offline/read-gate.js

@@ -0,0 +1,252 @@
+import { HonuaCapabilityNotSupportedError } from "../core/errors.js";
+import { sha256 } from "./digest.js";
+import { verifyOfflineRegionManifest } from "./region.js";
+import { OFFLINE_REGION_PROTOCOL, canonicalizeOfflineRegionQuery, compareOfflineRegionBounds, offlineRegionAuthorizationScopeDigest, offlineRegionQueryFingerprint, offlineRegionResourceId, } from "./selection.js";
+import { HonuaOfflineRegionError, } from "./types.js";
+/**
+ * The one gate every offline read passes through.
+ *
+ * Feature batches, tiles, assets, and metadata documents are different payloads
+ * answering different questions, but they are admitted by exactly the same
+ * discipline and in exactly the same order: region identity, then the caller's
+ * authorization scope, then version expectations, then extent, then expiry, then
+ * content-addressed lookup, then integrity. Keeping that order in one module is
+ * what makes "the narrowest true reason" a property of the contract rather than
+ * of whichever read path a caller happened to use.
+ *
+ * @experimental
+ */
+export const HONUA_OFFLINE_REGION_READ_KIND = "honua.offline-region-read";
+export const HONUA_OFFLINE_REGION_READ_VERSION = "1.0";
+/** Default age at which a region's observation is reported stale. */
+export const DEFAULT_OFFLINE_REGION_READ_STALE_AFTER_MS = 15 * 60 * 1000;
+/**
+ * Admit a read against a persisted region, or fail with the narrowest true reason.
+ *
+ * Nothing here touches stored bytes: every failure this raises is knowable from
+ * the manifest and the caller's own inputs, so an inadmissible read never causes
+ * a storage access at all.
+ */
+export async function openOfflineRegionRead(inputManifest, options) {
+    throwIfAborted(options.signal);
+    const manifest = await verifyOfflineRegionManifest(inputManifest);
+    const sourceId = manifest.source.id;
+    const authorizationScopeDigest = await offlineRegionAuthorizationScopeDigest(options.authorizationScopeFingerprint);
+    if (authorizationScopeDigest !== manifest.source.authorizationScopeDigest) {
+        // The single most important invariant: a scope change never reads another
+        // principal's cached bytes, and the failure names no scope material.
+        throw new HonuaOfflineRegionError("scope-mismatch", "Offline region belongs to a different authorization scope than this read.", { path: "authorizationScopeFingerprint" });
+    }
+    assertExpectedVersion(options.expect?.sourceVersion, manifest.source.sourceVersion, "sourceVersion");
+    assertExpectedVersion(options.expect?.schemaVersion, manifest.source.schemaVersion, "schemaVersion");
+    assertExpectedVersion(options.expect?.planVersion, manifest.source.planVersion, "planVersion");
+    if (options.bounds !== undefined) {
+        const relation = compareOfflineRegionBounds(options.bounds, manifest.bounds);
+        if (relation === "outside") {
+            throw new HonuaOfflineRegionError("out-of-region", "Requested extent is not covered by this offline region's bounds.", { path: "bounds" });
+        }
+        if (relation === "contained") {
+            // Narrowing to a sub-extent means evaluating a spatial predicate over the
+            // stored payload. Returning the wider snapshot instead would silently widen
+            // the caller's question, so the read refuses rather than approximates.
+            throw new HonuaCapabilityNotSupportedError("querySubExtent", OFFLINE_REGION_PROTOCOL, sourceId);
+        }
+    }
+    const scope = canonicalizeOfflineRegionQuery(options.query, sourceId);
+    const queryFingerprint = await offlineRegionQueryFingerprint(scope.canonical);
+    const now = (options.now ?? (() => new Date()))();
+    const nowMs = now.getTime();
+    if (!Number.isFinite(nowMs))
+        throw invalid("now must produce a valid Date.", "now");
+    if (manifest.expiresAt !== undefined && Date.parse(manifest.expiresAt) <= nowMs) {
+        throw new HonuaOfflineRegionError("expired", `Offline region "${manifest.id}" has expired.`, { path: "expiresAt" });
+    }
+    const observedAtMs = Date.parse(manifest.source.observation.observedAt);
+    const ageMs = Number.isFinite(observedAtMs) ? Math.max(0, nowMs - observedAtMs) : 0;
+    const staleAfterMs = normalizeStaleAfterMs(options.staleAfterMs);
+    return {
+        manifest,
+        sourceId,
+        authorizationScopeDigest,
+        selection: {
+            sourceId,
+            endpoint: manifest.source.endpoint,
+            authorizationScopeDigest,
+            sourceVersion: manifest.source.sourceVersion,
+            schemaVersion: manifest.source.schemaVersion,
+            planVersion: manifest.source.planVersion,
+            bounds: manifest.bounds,
+            ...(manifest.minZoom !== undefined ? { minZoom: manifest.minZoom } : {}),
+            ...(manifest.maxZoom !== undefined ? { maxZoom: manifest.maxZoom } : {}),
+        },
+        queryFingerprint,
+        pagination: scope.pagination,
+        now,
+        ageMs,
+        staleAfterMs,
+        freshness: ageMs >= staleAfterMs ? "stale" : "fresh",
+    };
+}
+/**
+ * Resolve a resource identity against the store and verify what comes back.
+ *
+ * The identity is content-addressed from the admitted selection, so a lookup can
+ * only ever find bytes stored for exactly this selection, kind, and selector; an
+ * absent entry is a miss rather than an empty success, and a stored payload that
+ * disagrees with its descriptor is an integrity failure rather than data.
+ */
+export async function readGatedOfflineRegionResource(gate, options) {
+    const resourceId = await offlineRegionResourceId({
+        kind: options.kind,
+        selection: gate.selection,
+        queryFingerprint: gate.queryFingerprint,
+        ...(options.selector !== undefined ? { selector: options.selector } : {}),
+    });
+    throwIfAborted(options.signal);
+    let read;
+    try {
+        read = await options.store.readResource(gate.manifest.id, resourceId);
+    }
+    catch (cause) {
+        if (cause instanceof HonuaOfflineRegionError)
+            throw cause;
+        throw new HonuaOfflineRegionError("store-failed", "Failed to read the offline region resource.", { cause });
+    }
+    if (!read) {
+        throw new HonuaOfflineRegionError("cache-miss", "This offline region holds no stored answer for the requested selection.", { resourceId });
+    }
+    if (read.regionId !== gate.manifest.id || read.resource.id !== resourceId) {
+        throw new HonuaOfflineRegionError("store-failed", "Offline region store returned a foreign resource.", {
+            resourceId,
+        });
+    }
+    if (read.resource.kind !== options.kind) {
+        throw new HonuaOfflineRegionError("cache-miss", `Stored resource for this selection is not a ${options.kind} resource.`, { resourceId });
+    }
+    const bytes = read.bytes;
+    if (bytes.byteLength !== read.resource.byteLength || (await sha256(bytes)) !== read.resource.integrity) {
+        throw new HonuaOfflineRegionError("integrity-mismatch", `Stored resource "${resourceId}" failed verification.`, {
+            resourceId,
+        });
+    }
+    return { resource: read.resource, bytes };
+}
+/** Report the persistent-cache decision for one admitted read. */
+export function createOfflineRegionReadCacheDecision(gate, resources, completeness) {
+    return {
+        kind: HONUA_OFFLINE_REGION_READ_KIND,
+        version: HONUA_OFFLINE_REGION_READ_VERSION,
+        policy: "prefer-cache",
+        action: "reuse",
+        state: "offline",
+        freshness: gate.freshness,
+        completeness,
+        reason: gate.freshness === "stale" ? "stale-entry" : "offline-entry",
+        regionId: gate.manifest.id,
+        queryFingerprint: gate.queryFingerprint,
+        authorizationScopeDigest: gate.authorizationScopeDigest,
+        observedAt: gate.manifest.source.observation.observedAt,
+        ageMs: gate.ageMs,
+        staleAfterMs: gate.staleAfterMs,
+        resources: resources.map((resource) => ({
+            id: resource.id,
+            kind: resource.kind,
+            byteLength: resource.byteLength,
+            integrity: resource.integrity,
+        })),
+    };
+}
+export function createOfflineRegionReadProvenance(gate) {
+    const manifest = gate.manifest;
+    return {
+        sourceId: gate.sourceId,
+        endpoint: manifest.source.endpoint,
+        authorizationScopeDigest: gate.authorizationScopeDigest,
+        sourceVersion: manifest.source.sourceVersion,
+        schemaVersion: manifest.source.schemaVersion,
+        planVersion: manifest.source.planVersion,
+        observation: manifest.source.observation,
+        ...(manifest.source.validator ? { validator: manifest.source.validator } : {}),
+    };
+}
+/**
+ * Every offline answer is a snapshot, so every offline answer says so.
+ *
+ * `capability` names the canonical capability the cached bytes stand in for — a
+ * tile read stands in for `tiles`, a rendering asset for `render`, and a feature
+ * or metadata read for `query` — so a consumer that checks degradation before
+ * treating an answer as authoritative learns which live capability it replaced.
+ */
+export function offlineRegionCachedSnapshotDegradation(gate, capability) {
+    const manifest = gate.manifest;
+    return {
+        capability,
+        reason: `Served from persisted offline region ${manifest.id} observed at ${manifest.source.observation.observedAt} (${gate.freshness}, ${gate.ageMs}ms old). This is a cached snapshot, not a live read.`,
+        sourceId: gate.sourceId,
+    };
+}
+/** Attribution for exactly the resources that answered a read. */
+export function pickOfflineRegionAttribution(manifest, resources) {
+    const out = {};
+    for (const resource of resources) {
+        for (const id of resource.attributionIds) {
+            const text = manifest.attribution[id];
+            if (typeof text === "string")
+                out[id] = text;
+        }
+    }
+    return out;
+}
+/**
+ * Cache input binding a query plan to a persisted region.
+ *
+ * A fresh region carries its manifest identity as a `fingerprint` validator, so
+ * the plan's own fingerprint changes when the region does. A stale region carries
+ * freshness only: reporting a validator would claim a revalidation the offline
+ * read will never perform.
+ */
+export function createOfflineRegionQueryPlanCache(manifest, options = {}) {
+    const nowMs = (options.now ?? new Date()).getTime();
+    const observedAtMs = Date.parse(manifest.source?.observation?.observedAt ?? "");
+    const staleAfterMs = normalizeStaleAfterMs(options.staleAfterMs);
+    const ageMs = Number.isFinite(observedAtMs) && Number.isFinite(nowMs) ? Math.max(0, nowMs - observedAtMs) : 0;
+    if (ageMs >= staleAfterMs)
+        return { policy: "prefer-cache", freshness: "stale" };
+    return {
+        policy: "prefer-cache",
+        freshness: "fresh",
+        validator: { kind: "fingerprint", fingerprint: manifest.id },
+    };
+}
+export function assertExpectedVersion(expected, actual, path) {
+    if (expected === undefined || expected === actual)
+        return;
+    throw new HonuaOfflineRegionError("out-of-region", `Offline region was captured at a different ${path} than this read expects.`, { path });
+}
+export function normalizeStaleAfterMs(value) {
+    if (value === undefined)
+        return DEFAULT_OFFLINE_REGION_READ_STALE_AFTER_MS;
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        throw invalid("staleAfterMs must be a non-negative safe integer.", "staleAfterMs");
+    }
+    return value;
+}
+export function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw new HonuaOfflineRegionError("aborted", "Offline region read was aborted.", { cause: signal.reason });
+    }
+}
+export function invalid(message, path) {
+    return new HonuaOfflineRegionError("invalid-manifest", message, { path });
+}
+/** Freeze a returned read. Typed arrays are caller-owned copies and stay writable. */
+export function deepFreezeRead(value) {
+    if (typeof value !== "object" || value === null || Object.isFrozen(value))
+        return value;
+    if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer)
+        return value;
+    Object.freeze(value);
+    for (const child of Object.values(value))
+        deepFreezeRead(child);
+    return value;
+}

package/offline/read-resource.d.ts

@@ -0,0 +1,99 @@
+import type { QueryTileKey, QueryTileKeyInput } from "../contract/tiles.js";
+import type { Capability, DegradedReason } from "../contract/types.js";
+import type { QueryPlanCacheOptions } from "../query-planner/types.js";
+import { HONUA_OFFLINE_REGION_READ_KIND, HONUA_OFFLINE_REGION_READ_VERSION, type OfflineRegionReadCacheDecisionV1, type OfflineRegionReadGateOptions, type OfflineRegionReadProvenanceV1, type OfflineRegionStoreReadOptions } from "./read-gate.js";
+import { type OfflineRegionResourceSelector, type OfflineRegionTileSelectorOptions } from "./selection.js";
+import { type OfflineRegionManifestV1, type OfflineRegionResourceKind } from "./types.js";
+/** Options shared by every non-feature read. */
+export interface ReadOfflineRegionResourceOptions extends OfflineRegionStoreReadOptions {
+    readonly kind: OfflineRegionResourceKind;
+    readonly selector?: OfflineRegionResourceSelector;
+    /** Canonical capability the cached bytes stand in for, reported on `degraded`. */
+    readonly capability?: Capability;
+}
+/** One opaque payload served from a persisted region. */
+export interface OfflineRegionResourceReadV1 {
+    readonly kind: typeof HONUA_OFFLINE_REGION_READ_KIND;
+    readonly version: typeof HONUA_OFFLINE_REGION_READ_VERSION;
+    readonly regionId: `sha256:${string}`;
+    readonly resourceKind: OfflineRegionResourceKind;
+    readonly resourceId: string;
+    /** Caller-owned bytes exactly as they were persisted; never re-encoded. */
+    readonly bytes: Uint8Array;
+    readonly contentType?: string;
+    readonly cache: OfflineRegionReadCacheDecisionV1;
+    readonly provenance: OfflineRegionReadProvenanceV1;
+    readonly attribution: Readonly<Record<string, string>>;
+    /**
+     * Same never-silently-live discipline a `Result` carries, in the same
+     * vocabulary. A binary read has no `Result` to stamp, so the degradation
+     * travels here.
+     */
+    readonly degraded: readonly DegradedReason[];
+    readonly planCache: QueryPlanCacheOptions;
+}
+/** A metadata document, plus its parsed form when it declares a JSON media type. */
+export interface OfflineRegionMetadataReadV1 extends OfflineRegionResourceReadV1 {
+    readonly resourceKind: "metadata";
+    /** Present only for a JSON media type; a non-JSON document stays bytes. */
+    readonly document?: unknown;
+}
+/** A tile payload, plus the canonical coordinate that addressed it. */
+export interface OfflineRegionTileReadV1 extends OfflineRegionResourceReadV1 {
+    readonly resourceKind: "tile";
+    readonly tile: QueryTileKey;
+}
+export interface ReadOfflineRegionTileOptions extends OfflineRegionStoreReadOptions, OfflineRegionTileSelectorOptions {
+    readonly tile: QueryTileKeyInput;
+}
+export interface ReadOfflineRegionAssetOptions extends OfflineRegionStoreReadOptions {
+    /** Stable asset key: a style id, glyph range, sprite name, or attachment id. */
+    readonly asset: string;
+    /** Canonical capability the cached bytes stand in for. Defaults to `render`. */
+    readonly capability?: Capability;
+}
+export interface ReadOfflineRegionMetadataOptions extends OfflineRegionStoreReadOptions {
+    /** Stable document name: a descriptor id, `landing-page`, `collections`, and so on. */
+    readonly document: string;
+}
+/**
+ * Resolve the content-addressed identity of one resource without reading it.
+ *
+ * This is what a host's own {@link OfflineRegionResourceMatcher} calls: the host
+ * parses its request URL into a tile key, asset key, or document name, asks for
+ * the identity, and hands it to the existing storage-backed fetch handler. The
+ * region is still verified, scoped, and expiry-checked here, so a matcher can
+ * never produce an identity for a region the caller may not read.
+ */
+export declare function resolveOfflineRegionResourceId(inputManifest: OfflineRegionManifestV1, options: OfflineRegionReadGateOptions & {
+    readonly kind: OfflineRegionResourceKind;
+    readonly selector?: OfflineRegionResourceSelector;
+}): Promise<string>;
+/**
+ * Read one stored resource of any kind from a persisted region.
+ *
+ * This is the primitive the tile, asset, and metadata reads are written in terms
+ * of; use it directly for the `attribution` kind or for a caller-defined selector.
+ */
+export declare function readOfflineRegionResource(inputManifest: OfflineRegionManifestV1, options: ReadOfflineRegionResourceOptions): Promise<OfflineRegionResourceReadV1>;
+/**
+ * Read one tile from a persisted region.
+ *
+ * Two coverage facts are knowable before any lookup and are reported as such: a
+ * zoom outside the region's own `minZoom`/`maxZoom`, and — when the region's CRS
+ * is provably WGS84 lon/lat — a tile whose envelope does not meet the region's
+ * bounds. Both are `out-of-region`, which is a truer answer than the cache miss
+ * that would otherwise follow, and neither touches storage.
+ */
+export declare function readOfflineRegionTile(inputManifest: OfflineRegionManifestV1, options: ReadOfflineRegionTileOptions): Promise<OfflineRegionTileReadV1>;
+/** Read one opaque asset — a style document, glyph range, sprite sheet, or attachment. */
+export declare function readOfflineRegionAsset(inputManifest: OfflineRegionManifestV1, options: ReadOfflineRegionAssetOptions): Promise<OfflineRegionResourceReadV1>;
+/**
+ * Read one metadata document — a source descriptor or a discovery response.
+ *
+ * A document whose stored media type declares JSON is parsed as well as returned;
+ * bytes that verified against their digest but cannot be parsed as the media type
+ * they declare are an integrity failure, not a document.
+ */
+export declare function readOfflineRegionMetadata(inputManifest: OfflineRegionManifestV1, options: ReadOfflineRegionMetadataOptions): Promise<OfflineRegionMetadataReadV1>;
+//# sourceMappingURL=read-resource.d.ts.map

package/offline/read-resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-resource.d.ts","sourceRoot":"","sources":["../../../src/offline/read-resource.ts"],"names":[],"mappings":"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"}

package/offline/read-resource.js

@@ -0,0 +1,156 @@
+import { HONUA_OFFLINE_REGION_READ_KIND, HONUA_OFFLINE_REGION_READ_VERSION, createOfflineRegionQueryPlanCache, createOfflineRegionReadCacheDecision, createOfflineRegionReadProvenance, deepFreezeRead, offlineRegionCachedSnapshotDegradation, openOfflineRegionRead, pickOfflineRegionAttribution, readGatedOfflineRegionResource, } from "./read-gate.js";
+import { isWgs84LonLatCrs, normalizeOfflineRegionTileKey, offlineRegionAssetSelector, offlineRegionMetadataSelector, offlineRegionResourceId, offlineRegionTileEnvelope, offlineRegionTileSelector, } from "./selection.js";
+import { HonuaOfflineRegionError } from "./types.js";
+/**
+ * Serving tiles, assets, and metadata documents from a persisted region.
+ *
+ * These are the read kinds the region model has always stored but nothing could
+ * read back: raster and vector tiles, style/glyph/sprite and attachment assets,
+ * and descriptor or discovery documents. They pass the same gate a feature read
+ * does — region identity, authorization scope, versions, extent, expiry,
+ * content-addressed lookup, integrity — and they answer with opaque bytes and
+ * their declared media type. The SDK never re-encodes a tile or an asset, and
+ * never synthesizes one it does not hold.
+ *
+ * @experimental
+ */
+const JSON_MEDIA_TYPES = new Set([
+    "application/json",
+    "application/geo+json",
+    "application/schema+json",
+    "application/vnd.mapbox-vector-tile+json",
+    "text/json",
+]);
+/**
+ * Resolve the content-addressed identity of one resource without reading it.
+ *
+ * This is what a host's own {@link OfflineRegionResourceMatcher} calls: the host
+ * parses its request URL into a tile key, asset key, or document name, asks for
+ * the identity, and hands it to the existing storage-backed fetch handler. The
+ * region is still verified, scoped, and expiry-checked here, so a matcher can
+ * never produce an identity for a region the caller may not read.
+ */
+export async function resolveOfflineRegionResourceId(inputManifest, options) {
+    const gate = await openOfflineRegionRead(inputManifest, options);
+    return offlineRegionResourceId({
+        kind: options.kind,
+        selection: gate.selection,
+        queryFingerprint: gate.queryFingerprint,
+        ...(options.selector !== undefined ? { selector: options.selector } : {}),
+    });
+}
+/**
+ * Read one stored resource of any kind from a persisted region.
+ *
+ * This is the primitive the tile, asset, and metadata reads are written in terms
+ * of; use it directly for the `attribution` kind or for a caller-defined selector.
+ */
+export async function readOfflineRegionResource(inputManifest, options) {
+    const gate = await openOfflineRegionRead(inputManifest, options);
+    return completeResourceRead(gate, options, options.kind, options.capability ?? "query");
+}
+/**
+ * Read one tile from a persisted region.
+ *
+ * Two coverage facts are knowable before any lookup and are reported as such: a
+ * zoom outside the region's own `minZoom`/`maxZoom`, and — when the region's CRS
+ * is provably WGS84 lon/lat — a tile whose envelope does not meet the region's
+ * bounds. Both are `out-of-region`, which is a truer answer than the cache miss
+ * that would otherwise follow, and neither touches storage.
+ */
+export async function readOfflineRegionTile(inputManifest, options) {
+    const gate = await openOfflineRegionRead(inputManifest, options);
+    const tile = normalizeOfflineRegionTileKey(options.tile, options);
+    assertTileWithinRegion(gate, tile);
+    const selector = offlineRegionTileSelector(tile, {
+        ...(options.tileMatrixSetId !== undefined ? { tileMatrixSetId: options.tileMatrixSetId } : {}),
+    });
+    const read = await completeResourceRead(gate, { ...options, selector }, "tile", "tiles");
+    return deepFreezeRead({ ...read, resourceKind: "tile", tile });
+}
+/** Read one opaque asset — a style document, glyph range, sprite sheet, or attachment. */
+export async function readOfflineRegionAsset(inputManifest, options) {
+    const gate = await openOfflineRegionRead(inputManifest, options);
+    const selector = offlineRegionAssetSelector(options.asset);
+    return completeResourceRead(gate, { ...options, selector }, "asset", options.capability ?? "render");
+}
+/**
+ * Read one metadata document — a source descriptor or a discovery response.
+ *
+ * A document whose stored media type declares JSON is parsed as well as returned;
+ * bytes that verified against their digest but cannot be parsed as the media type
+ * they declare are an integrity failure, not a document.
+ */
+export async function readOfflineRegionMetadata(inputManifest, options) {
+    const gate = await openOfflineRegionRead(inputManifest, options);
+    const selector = offlineRegionMetadataSelector(options.document);
+    const read = await completeResourceRead(gate, { ...options, selector }, "metadata", "query");
+    const document = isJsonMediaType(read.contentType) ? parseJsonDocument(read.bytes, read.resourceId) : undefined;
+    return deepFreezeRead({
+        ...read,
+        resourceKind: "metadata",
+        ...(document === undefined ? {} : { document }),
+    });
+}
+async function completeResourceRead(gate, options, kind, capability) {
+    const { resource, bytes } = await readGatedOfflineRegionResource(gate, {
+        store: options.store,
+        kind,
+        ...(options.selector !== undefined ? { selector: options.selector } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+    });
+    return deepFreezeRead({
+        kind: HONUA_OFFLINE_REGION_READ_KIND,
+        version: HONUA_OFFLINE_REGION_READ_VERSION,
+        regionId: gate.manifest.id,
+        resourceKind: kind,
+        resourceId: resource.id,
+        bytes,
+        ...(resource.contentType ? { contentType: resource.contentType } : {}),
+        // A single opaque payload is either present in full or absent: there is no
+        // partial tile, so completeness is never inferred from byte counts.
+        cache: createOfflineRegionReadCacheDecision(gate, [resource], "complete"),
+        provenance: createOfflineRegionReadProvenance(gate),
+        attribution: pickOfflineRegionAttribution(gate.manifest, [resource]),
+        degraded: [offlineRegionCachedSnapshotDegradation(gate, capability)],
+        planCache: createOfflineRegionQueryPlanCache(gate.manifest, {
+            now: gate.now,
+            staleAfterMs: gate.staleAfterMs,
+        }),
+    });
+}
+function assertTileWithinRegion(gate, tile) {
+    const manifest = gate.manifest;
+    if (manifest.minZoom !== undefined && tile.z < manifest.minZoom) {
+        throw new HonuaOfflineRegionError("out-of-region", `Requested zoom ${tile.z} is below this offline region's minimum zoom ${manifest.minZoom}.`, { path: "tile.z" });
+    }
+    if (manifest.maxZoom !== undefined && tile.z > manifest.maxZoom) {
+        throw new HonuaOfflineRegionError("out-of-region", `Requested zoom ${tile.z} is above this offline region's maximum zoom ${manifest.maxZoom}.`, { path: "tile.z" });
+    }
+    // A CRS the SDK cannot prove is WGS84 lon/lat gets no geometric claim at all;
+    // identity still gates the read, so an uncovered tile is simply a miss.
+    if (!isWgs84LonLatCrs(manifest.bounds.crs))
+        return;
+    const envelope = offlineRegionTileEnvelope(tile);
+    const disjoint = envelope.maxX <= manifest.bounds.minX ||
+        envelope.minX >= manifest.bounds.maxX ||
+        envelope.maxY <= manifest.bounds.minY ||
+        envelope.minY >= manifest.bounds.maxY;
+    if (disjoint) {
+        throw new HonuaOfflineRegionError("out-of-region", `Requested tile ${tile.z}/${tile.x}/${tile.y} lies outside this offline region's bounds.`, { path: "tile" });
+    }
+}
+function isJsonMediaType(contentType) {
+    if (!contentType)
+        return false;
+    const essence = contentType.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+    return JSON_MEDIA_TYPES.has(essence) || essence.endsWith("+json");
+}
+function parseJsonDocument(bytes, resourceId) {
+    try {
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch (cause) {
+        throw new HonuaOfflineRegionError("integrity-mismatch", `Stored metadata document "${resourceId}" is not valid JSON for its declared media type.`, { cause, resourceId });
+    }
+}

package/offline/read.d.ts

@@ -0,0 +1,50 @@
+import type { Query, Result } from "../contract/types.js";
+import type { QueryPlanCacheOptions } from "../query-planner/types.js";
+import { HONUA_OFFLINE_REGION_READ_KIND, HONUA_OFFLINE_REGION_READ_VERSION, type OfflineRegionReadCacheDecisionV1, type OfflineRegionReadProvenanceV1, type OfflineRegionStoreReadOptions } from "./read-gate.js";
+import type { OfflineRegionResourceSelector } from "./selection.js";
+import { type OfflineRegionManifestV1 } from "./types.js";
+/**
+ * Answering a protocol-neutral `Query` from a persisted region.
+ *
+ * The read path is deliberately narrow. It replays the snapshot a selection
+ * captured and refines only the pagination window, because that is the one
+ * refinement a stored batch can honour exactly. Everything else fails closed: a
+ * construct the region cannot answer raises `HonuaCapabilityNotSupportedError`,
+ * and a selection the region does not cover raises a typed cache miss. Nothing
+ * here reaches the network, revalidates, or widens a query, and no result is ever
+ * presented as live.
+ *
+ * @experimental
+ */
+export interface ReadOfflineRegionQueryOptions<T = Record<string, unknown>> extends Omit<OfflineRegionStoreReadOptions, "query"> {
+    /** Protocol-neutral query intent. Omitted means the snapshot's own selection. */
+    readonly query?: Query<T>;
+    /** Discriminator when a selection stores several feature batches. */
+    readonly selector?: OfflineRegionResourceSelector;
+}
+export interface OfflineRegionQueryReadV1<T = Record<string, unknown>> {
+    readonly kind: typeof HONUA_OFFLINE_REGION_READ_KIND;
+    readonly version: typeof HONUA_OFFLINE_REGION_READ_VERSION;
+    readonly regionId: `sha256:${string}`;
+    readonly result: Result<T>;
+    readonly cache: OfflineRegionReadCacheDecisionV1;
+    readonly provenance: OfflineRegionReadProvenanceV1;
+    /** Attribution for the resources that answered the read. */
+    readonly attribution: Readonly<Record<string, string>>;
+    /**
+     * Cache input for `explainQuery()`, so the query plan reports this read.
+     * A fresh region carries its manifest identity as the plan's validator; a stale
+     * one deliberately carries none, because a region can be reported stale but
+     * never revalidated without the network the caller does not have.
+     */
+    readonly planCache: QueryPlanCacheOptions;
+}
+/**
+ * Answer `query` from a persisted region, or fail closed.
+ *
+ * Order matters: the region's identity, then the caller's authorization scope,
+ * then version expectations, then the extent, then the query's constructs, then
+ * expiry — each failing with the narrowest true reason before any bytes are read.
+ */
+export declare function readOfflineRegionQuery<T = Record<string, unknown>>(inputManifest: OfflineRegionManifestV1, options: ReadOfflineRegionQueryOptions<T>): Promise<OfflineRegionQueryReadV1<T>>;
+//# sourceMappingURL=read.d.ts.map

package/offline/read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../../src/offline/read.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EACL,8BAA8B,EAC9B,iCAAiC,EACjC,KAAK,gCAAgC,EAErC,KAAK,6BAA6B,EAClC,KAAK,6BAA6B,EASnC,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,gBAAgB,CAAC;AAEpE,OAAO,EAA2B,KAAK,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAEnF;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,6BAA6B,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CACxE,SAAQ,IAAI,CAAC,6BAA6B,EAAE,OAAO,CAAC;IACpD,iFAAiF;IACjF,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,6BAA6B,CAAC;CACnD;AAED,MAAM,WAAW,wBAAwB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACnE,QAAQ,CAAC,IAAI,EAAE,OAAO,8BAA8B,CAAC;IACrD,QAAQ,CAAC,OAAO,EAAE,OAAO,iCAAiC,CAAC;IAC3D,QAAQ,CAAC,QAAQ,EAAE,UAAU,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,gCAAgC,CAAC;IACjD,QAAQ,CAAC,UAAU,EAAE,6BAA6B,CAAC;IACnD,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACvD;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,qBAAqB,CAAC;CAC3C;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtE,aAAa,EAAE,uBAAuB,EACtC,OAAO,EAAE,6BAA6B,CAAC,CAAC,CAAC,GACxC,OAAO,CAAC,wBAAwB,CAAC,CAAC,CAAC,CAAC,CAiCtC"}

package/offline/read.js

@@ -0,0 +1,65 @@
+import { HONUA_OFFLINE_REGION_READ_KIND, HONUA_OFFLINE_REGION_READ_VERSION, createOfflineRegionQueryPlanCache, createOfflineRegionReadCacheDecision, createOfflineRegionReadProvenance, deepFreezeRead, offlineRegionCachedSnapshotDegradation, openOfflineRegionRead, pickOfflineRegionAttribution, readGatedOfflineRegionResource, } from "./read-gate.js";
+import { decodeOfflineRegionFeatureBatch } from "./snapshot.js";
+import { HonuaOfflineRegionError } from "./types.js";
+/**
+ * Answer `query` from a persisted region, or fail closed.
+ *
+ * Order matters: the region's identity, then the caller's authorization scope,
+ * then version expectations, then the extent, then the query's constructs, then
+ * expiry — each failing with the narrowest true reason before any bytes are read.
+ */
+export async function readOfflineRegionQuery(inputManifest, options) {
+    const gate = await openOfflineRegionRead(inputManifest, options);
+    const { resource, bytes } = await readGatedOfflineRegionResource(gate, {
+        store: options.store,
+        kind: "features",
+        ...(options.selector !== undefined ? { selector: options.selector } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+    });
+    const batch = decodeOfflineRegionFeatureBatch(bytes);
+    const window = resolveWindow(batch, gate.pagination, resource.id);
+    const result = {
+        features: window.features,
+        exceededTransferLimit: window.exceededTransferLimit,
+        ...(batch.totalCount === undefined ? {} : { totalCount: batch.totalCount }),
+        ...(batch.fields === undefined ? {} : { fields: batch.fields }),
+        degraded: [offlineRegionCachedSnapshotDegradation(gate, "query")],
+    };
+    return deepFreezeRead({
+        kind: HONUA_OFFLINE_REGION_READ_KIND,
+        version: HONUA_OFFLINE_REGION_READ_VERSION,
+        regionId: gate.manifest.id,
+        result,
+        cache: createOfflineRegionReadCacheDecision(gate, [resource], batch.exceededTransferLimit ? "partial" : "complete"),
+        provenance: createOfflineRegionReadProvenance(gate),
+        attribution: pickOfflineRegionAttribution(gate.manifest, [resource]),
+        planCache: createOfflineRegionQueryPlanCache(gate.manifest, {
+            now: gate.now,
+            staleAfterMs: gate.staleAfterMs,
+        }),
+    });
+}
+/**
+ * Slice the stored batch to the requested window, or refuse.
+ *
+ * A stored batch covers `[offset, offset + features.length)` and, when it did not
+ * exceed its transfer limit, everything after that too — because nothing else
+ * matched. A request outside that coverage is a miss, never a short answer.
+ */
+function resolveWindow(batch, requested, resourceId) {
+    const storedStart = batch.pagination.offset;
+    const storedEnd = storedStart + batch.features.length;
+    const requestedStart = requested.offset;
+    const requestedEnd = requested.limit === undefined ? Number.POSITIVE_INFINITY : requestedStart + requested.limit;
+    const coveredEnd = batch.exceededTransferLimit ? storedEnd : Number.POSITIVE_INFINITY;
+    if (requestedStart < storedStart || requestedEnd > coveredEnd) {
+        throw new HonuaOfflineRegionError("cache-miss", "Requested page is outside the window this offline region captured.", { resourceId });
+    }
+    const sliceStart = Math.min(requestedStart - storedStart, batch.features.length);
+    const sliceEnd = requested.limit === undefined
+        ? batch.features.length
+        : Math.min(sliceStart + requested.limit, batch.features.length);
+    const features = batch.features.slice(sliceStart, sliceEnd);
+    const moreInBatch = sliceEnd < batch.features.length;
+    return { features, exceededTransferLimit: moreInBatch || batch.exceededTransferLimit };
+}