@honua/app-platform 0.1.12 → 0.1.14

package/offline/selection.d.ts

@@ -0,0 +1,140 @@
+import type { QueryTileKey, QueryTileKeyInput, QueryTileScheme } from "../contract/tiles.js";
+import type { Query } from "../contract/types.js";
+import { type OfflineRegionBounds, type OfflineRegionResourceKind } from "./types.js";
+/**
+ * Protocol-neutral selection identity for offline reads.
+ *
+ * A persisted region is addressed by what the caller asked for — a source, a
+ * canonical query, a bounded extent, an authorization scope, and the source /
+ * schema / plan versions it was captured at — never by a request URL. Snapshot
+ * planning and the read path both derive resource identity here, so a read can
+ * only ever find bytes that were stored for exactly that selection.
+ *
+ * @experimental
+ */
+/** Protocol name reported by capability failures raised on the offline read path. */
+export declare const OFFLINE_REGION_PROTOCOL: "offline-region";
+/**
+ * Kind-specific discriminator that separates several resources of one kind
+ * inside a single selection: tile coordinates, an asset key, or a document name.
+ * Values are credential-screened and persisted only inside a digest.
+ */
+export type OfflineRegionResourceSelector = string | number | readonly (string | number)[];
+/**
+ * The pagination-free canonical form of a {@link Query}.
+ *
+ * Every constraint that changes *which* records match is part of this value and
+ * therefore part of resource identity. Pagination is deliberately excluded: it
+ * selects a window over an already-determined match set, and the read path
+ * answers it from the stored batch's own recorded window instead of pretending a
+ * different page was captured.
+ */
+export interface OfflineRegionCanonicalQueryV1 {
+    readonly filter: unknown;
+    readonly temporalFilter: unknown;
+    readonly where: string | null;
+    readonly spatialFilter: unknown;
+    readonly outFields: readonly string[] | null;
+    readonly orderBy: readonly {
+        readonly field: string;
+        readonly direction: "asc" | "desc";
+    }[] | null;
+    readonly returnGeometry: boolean | null;
+    readonly outSr: string | number | null;
+}
+/** A canonical query plus the pagination window the caller asked for. */
+export interface OfflineRegionQueryScopeV1 {
+    readonly canonical: OfflineRegionCanonicalQueryV1;
+    readonly pagination: {
+        readonly offset: number;
+        readonly limit?: number;
+    };
+}
+/** Credential-free, protocol-neutral identity of one offline selection. */
+export interface OfflineRegionSelectionIdentityV1 {
+    readonly sourceId: string;
+    /** Already-normalized credential-free endpoint identity. */
+    readonly endpoint: string;
+    readonly authorizationScopeDigest: `sha256:${string}`;
+    readonly sourceVersion: string;
+    readonly schemaVersion: string;
+    readonly planVersion: string;
+    readonly bounds: OfflineRegionBounds;
+    readonly minZoom?: number;
+    readonly maxZoom?: number;
+}
+/**
+ * Reduce a {@link Query} to its canonical identity plus its pagination window.
+ *
+ * Fails closed twice over. An unknown member is refused rather than dropped,
+ * because dropping it would answer a narrower question than the caller asked;
+ * and `aggregation` is refused outright, because a stored feature batch is not
+ * an aggregate and computing one locally would return a number the region never
+ * observed.
+ */
+export declare function canonicalizeOfflineRegionQuery(query?: Query, sourceId?: string): OfflineRegionQueryScopeV1;
+/** Domain-separated fingerprint of a canonical query. */
+export declare function offlineRegionQueryFingerprint(canonical: OfflineRegionCanonicalQueryV1): Promise<`sha256:${string}`>;
+/**
+ * Deterministic, credential-free identity for one resource of one selection.
+ *
+ * The digest binds the resource kind, its selector, the source identity, the
+ * authorization-scope digest, the captured versions, the bounded extent, and the
+ * canonical query. Two selections that differ in any of those — including a
+ * scope change — can never address the same stored bytes.
+ */
+export declare function offlineRegionResourceId(input: {
+    readonly kind: OfflineRegionResourceKind;
+    readonly selection: OfflineRegionSelectionIdentityV1;
+    readonly queryFingerprint: `sha256:${string}`;
+    readonly selector?: OfflineRegionResourceSelector;
+}): Promise<string>;
+/**
+ * Digest of the opaque authorization-scope partition input. Never persisted raw.
+ *
+ * Domain separation and the trimmed pre-image match
+ * `createOfflineRegionManifest()` exactly, so a read can compare its caller's
+ * current scope against a stored manifest's digest without re-deriving either.
+ */
+export declare function offlineRegionAuthorizationScopeDigest(fingerprint: string): Promise<`sha256:${string}`>;
+/** Highest tile zoom an offline region can address, matching the manifest's own ceiling. */
+export declare const OFFLINE_REGION_MAX_TILE_ZOOM = 30;
+/** Default tile-matrix-set discriminator for a region that names none. */
+export declare const OFFLINE_REGION_DEFAULT_TILE_MATRIX_SET = "default";
+export interface OfflineRegionTileSelectorOptions {
+    /** `tms` rows are folded onto their canonical XYZ row before addressing. */
+    readonly scheme?: QueryTileScheme;
+    /** Separates pyramids that share coordinates but not a grid (for example an OGC tile-matrix set). */
+    readonly tileMatrixSetId?: string;
+}
+/**
+ * Fold a tile coordinate onto the canonical XYZ identity an offline region stores.
+ *
+ * This reuses the contract's {@link QueryTileKey} vocabulary but deliberately not
+ * `normalizeQueryTileKey()`, whose clamping is right for a renderer and wrong for
+ * a content-addressed cache: clamping an out-of-range row would quietly address a
+ * *different* tile's bytes. Longitude wrapping is kept, because a wrapped column
+ * is the same geographic tile; an out-of-range row or zoom is refused instead.
+ */
+export declare function normalizeOfflineRegionTileKey(input: QueryTileKeyInput, options?: OfflineRegionTileSelectorOptions): QueryTileKey;
+/** Deterministic selector addressing one tile inside a selection. */
+export declare function offlineRegionTileSelector(tile: QueryTileKeyInput, options?: OfflineRegionTileSelectorOptions): OfflineRegionResourceSelector;
+/** Deterministic selector addressing one opaque asset (style, glyph, sprite, attachment). */
+export declare function offlineRegionAssetSelector(key: string): OfflineRegionResourceSelector;
+/** Deterministic selector addressing one metadata document (descriptor, discovery response). */
+export declare function offlineRegionMetadataSelector(document: string): OfflineRegionResourceSelector;
+/** WGS84 lon/lat envelope of a canonical XYZ tile, in the Web Mercator pyramid. */
+export declare function offlineRegionTileEnvelope(tile: QueryTileKey): OfflineRegionBounds;
+/**
+ * Whether a declared CRS is provably WGS84 longitude/latitude.
+ *
+ * Only a recognized identifier returns `true`. An unrecognized CRS makes no
+ * claim either way, so callers must not treat `false` as "not WGS84" — they must
+ * treat it as "cannot compare geometrically", and fall back to identity alone.
+ */
+export declare function isWgs84LonLatCrs(crs: string): boolean;
+/** How a requested extent relates to a stored region's extent. */
+export type OfflineRegionBoundsRelation = "equal" | "contained" | "outside";
+/** Compare a requested extent to a region extent in the region's own CRS. */
+export declare function compareOfflineRegionBounds(requested: OfflineRegionBounds, region: OfflineRegionBounds): OfflineRegionBoundsRelation;
+//# sourceMappingURL=selection.d.ts.map

package/offline/selection.d.ts.map

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

package/offline/selection.js

@@ -0,0 +1,391 @@
+import { HonuaCapabilityNotSupportedError } from "../core/errors.js";
+import { screenPersistedString } from "./credential-screen.js";
+import { canonicalJson, compareCodeUnits, identityDigest, sha256 } from "./digest.js";
+import { HonuaOfflineRegionError } from "./types.js";
+/**
+ * Protocol-neutral selection identity for offline reads.
+ *
+ * A persisted region is addressed by what the caller asked for — a source, a
+ * canonical query, a bounded extent, an authorization scope, and the source /
+ * schema / plan versions it was captured at — never by a request URL. Snapshot
+ * planning and the read path both derive resource identity here, so a read can
+ * only ever find bytes that were stored for exactly that selection.
+ *
+ * @experimental
+ */
+/** Protocol name reported by capability failures raised on the offline read path. */
+export const OFFLINE_REGION_PROTOCOL = "offline-region";
+/** Query members the offline read path understands. Anything else fails closed. */
+const SUPPORTED_QUERY_KEYS = new Set([
+    "filter",
+    "temporalFilter",
+    "where",
+    "spatialFilter",
+    "outFields",
+    "orderBy",
+    "pagination",
+    "aggregation",
+    "returnGeometry",
+    "outSr",
+    "signal",
+]);
+const MAX_SELECTOR_SEGMENTS = 16;
+const MAX_SELECTOR_TEXT_LENGTH = 512;
+const MAX_CANONICAL_QUERY_BYTES = 64 * 1024;
+const MAX_QUERY_DEPTH = 32;
+/**
+ * Reduce a {@link Query} to its canonical identity plus its pagination window.
+ *
+ * Fails closed twice over. An unknown member is refused rather than dropped,
+ * because dropping it would answer a narrower question than the caller asked;
+ * and `aggregation` is refused outright, because a stored feature batch is not
+ * an aggregate and computing one locally would return a number the region never
+ * observed.
+ */
+export function canonicalizeOfflineRegionQuery(query, sourceId) {
+    if (query === undefined)
+        return { canonical: emptyCanonicalQuery(), pagination: { offset: 0 } };
+    const record = plainRecord(query, "query");
+    for (const key in record) {
+        if (Object.hasOwn(record, key) && !SUPPORTED_QUERY_KEYS.has(key)) {
+            throw new HonuaCapabilityNotSupportedError(`query.${key}`, OFFLINE_REGION_PROTOCOL, sourceId, {
+                context: { reasonCode: "unsupported-query-member" },
+            });
+        }
+    }
+    if (record.aggregation !== undefined) {
+        throw new HonuaCapabilityNotSupportedError("queryAggregate", OFFLINE_REGION_PROTOCOL, sourceId, {
+            context: { reasonCode: "aggregation-not-stored" },
+        });
+    }
+    const canonical = {
+        filter: jsonValue(record.filter, "query.filter"),
+        temporalFilter: jsonValue(record.temporalFilter, "query.temporalFilter"),
+        where: optionalText(record.where, "query.where"),
+        spatialFilter: jsonValue(record.spatialFilter, "query.spatialFilter"),
+        outFields: normalizeOutFields(record.outFields),
+        orderBy: normalizeOrderBy(record.orderBy),
+        returnGeometry: record.returnGeometry === undefined ? null : requireBoolean(record.returnGeometry, "query.returnGeometry"),
+        outSr: normalizeOutSr(record.outSr),
+    };
+    const encoded = canonicalJson(canonical);
+    if (encoded.length > MAX_CANONICAL_QUERY_BYTES) {
+        throw invalid("query exceeds the canonical offline identity budget.", "query");
+    }
+    return { canonical, pagination: normalizePagination(record.pagination) };
+}
+/** Domain-separated fingerprint of a canonical query. */
+export function offlineRegionQueryFingerprint(canonical) {
+    return identityDigest("honua-offline-query", canonical);
+}
+/**
+ * Deterministic, credential-free identity for one resource of one selection.
+ *
+ * The digest binds the resource kind, its selector, the source identity, the
+ * authorization-scope digest, the captured versions, the bounded extent, and the
+ * canonical query. Two selections that differ in any of those — including a
+ * scope change — can never address the same stored bytes.
+ */
+export async function offlineRegionResourceId(input) {
+    const kind = input.kind;
+    const digest = await identityDigest("honua-offline-resource", {
+        kind,
+        selector: normalizeSelector(input.selector),
+        query: input.queryFingerprint,
+        source: {
+            id: input.selection.sourceId,
+            endpoint: input.selection.endpoint,
+            authorizationScopeDigest: input.selection.authorizationScopeDigest,
+            sourceVersion: input.selection.sourceVersion,
+            schemaVersion: input.selection.schemaVersion,
+            planVersion: input.selection.planVersion,
+        },
+        bounds: input.selection.bounds,
+        minZoom: input.selection.minZoom ?? null,
+        maxZoom: input.selection.maxZoom ?? null,
+    });
+    return `${kind}/${digest.slice("sha256:".length)}`;
+}
+/**
+ * Digest of the opaque authorization-scope partition input. Never persisted raw.
+ *
+ * Domain separation and the trimmed pre-image match
+ * `createOfflineRegionManifest()` exactly, so a read can compare its caller's
+ * current scope against a stored manifest's digest without re-deriving either.
+ */
+export function offlineRegionAuthorizationScopeDigest(fingerprint) {
+    if (typeof fingerprint !== "string" || fingerprint.trim().length === 0) {
+        throw invalid("authorizationScopeFingerprint must be a non-empty string.", "authorizationScopeFingerprint");
+    }
+    return sha256(`honua-offline-scope:v1:${fingerprint.trim()}`);
+}
+/** Highest tile zoom an offline region can address, matching the manifest's own ceiling. */
+export const OFFLINE_REGION_MAX_TILE_ZOOM = 30;
+/** Default tile-matrix-set discriminator for a region that names none. */
+export const OFFLINE_REGION_DEFAULT_TILE_MATRIX_SET = "default";
+/**
+ * Fold a tile coordinate onto the canonical XYZ identity an offline region stores.
+ *
+ * This reuses the contract's {@link QueryTileKey} vocabulary but deliberately not
+ * `normalizeQueryTileKey()`, whose clamping is right for a renderer and wrong for
+ * a content-addressed cache: clamping an out-of-range row would quietly address a
+ * *different* tile's bytes. Longitude wrapping is kept, because a wrapped column
+ * is the same geographic tile; an out-of-range row or zoom is refused instead.
+ */
+export function normalizeOfflineRegionTileKey(input, options = {}) {
+    const scheme = options.scheme ?? "xyz";
+    if (scheme !== "xyz" && scheme !== "tms")
+        throw invalid("tile scheme must be xyz or tms.", "tile.scheme");
+    const z = tileInteger(input.z ?? input.tileMatrix, "tile.z");
+    const x = tileInteger(input.x ?? input.tileCol, "tile.x");
+    const y = tileInteger(input.y ?? input.tileRow, "tile.y");
+    if (z < 0 || z > OFFLINE_REGION_MAX_TILE_ZOOM) {
+        throw new HonuaOfflineRegionError("out-of-region", `tile.z must be between 0 and ${OFFLINE_REGION_MAX_TILE_ZOOM}.`, { path: "tile.z" });
+    }
+    const tileCount = 2 ** z;
+    if (y < 0 || y >= tileCount) {
+        throw new HonuaOfflineRegionError("out-of-region", `tile.y is outside the zoom-${z} tile pyramid.`, {
+            path: "tile.y",
+        });
+    }
+    return { z, x: ((x % tileCount) + tileCount) % tileCount, y: scheme === "tms" ? tileCount - 1 - y : y };
+}
+/** Deterministic selector addressing one tile inside a selection. */
+export function offlineRegionTileSelector(tile, options = {}) {
+    const key = normalizeOfflineRegionTileKey(tile, options);
+    const set = options.tileMatrixSetId ?? OFFLINE_REGION_DEFAULT_TILE_MATRIX_SET;
+    return ["tile", boundedIdentity(set, "tileMatrixSetId"), key.z, key.x, key.y];
+}
+/** Deterministic selector addressing one opaque asset (style, glyph, sprite, attachment). */
+export function offlineRegionAssetSelector(key) {
+    return ["asset", boundedIdentity(key, "asset")];
+}
+/** Deterministic selector addressing one metadata document (descriptor, discovery response). */
+export function offlineRegionMetadataSelector(document) {
+    return ["metadata", boundedIdentity(document, "document")];
+}
+/** WGS84 lon/lat envelope of a canonical XYZ tile, in the Web Mercator pyramid. */
+export function offlineRegionTileEnvelope(tile) {
+    const tileCount = 2 ** tile.z;
+    return {
+        minX: (tile.x / tileCount) * 360 - 180,
+        minY: mercatorLatitude((tile.y + 1) / tileCount),
+        maxX: ((tile.x + 1) / tileCount) * 360 - 180,
+        maxY: mercatorLatitude(tile.y / tileCount),
+        crs: "EPSG:4326",
+    };
+}
+const WGS84_LON_LAT_CRS = new Set([
+    "epsg:4326",
+    "crs:84",
+    "crs84",
+    "ogc:crs84",
+    "urn:ogc:def:crs:ogc:1.3:crs84",
+    "urn:ogc:def:crs:ogc::crs84",
+    "urn:ogc:def:crs:epsg::4326",
+    "http://www.opengis.net/def/crs/ogc/1.3/crs84",
+    "http://www.opengis.net/def/crs/epsg/0/4326",
+]);
+/**
+ * Whether a declared CRS is provably WGS84 longitude/latitude.
+ *
+ * Only a recognized identifier returns `true`. An unrecognized CRS makes no
+ * claim either way, so callers must not treat `false` as "not WGS84" — they must
+ * treat it as "cannot compare geometrically", and fall back to identity alone.
+ */
+export function isWgs84LonLatCrs(crs) {
+    return typeof crs === "string" && WGS84_LON_LAT_CRS.has(crs.trim().toLowerCase());
+}
+/** Compare a requested extent to a region extent in the region's own CRS. */
+export function compareOfflineRegionBounds(requested, region) {
+    if (requested.crs !== region.crs)
+        return "outside";
+    if (requested.minX === region.minX &&
+        requested.minY === region.minY &&
+        requested.maxX === region.maxX &&
+        requested.maxY === region.maxY) {
+        return "equal";
+    }
+    const contained = requested.minX >= region.minX &&
+        requested.minY >= region.minY &&
+        requested.maxX <= region.maxX &&
+        requested.maxY <= region.maxY;
+    return contained ? "contained" : "outside";
+}
+/** Latitude of a Web Mercator row fraction, in degrees. */
+function mercatorLatitude(fraction) {
+    return (Math.atan(Math.sinh(Math.PI * (1 - 2 * fraction))) * 180) / Math.PI;
+}
+function tileInteger(value, path) {
+    const parsed = typeof value === "string" ? Number(value) : value;
+    if (typeof parsed !== "number" || !Number.isSafeInteger(parsed)) {
+        throw invalid(`${path} must be an integer.`, path);
+    }
+    return parsed;
+}
+function boundedIdentity(value, path) {
+    if (typeof value !== "string" || value.length === 0 || value.length > MAX_SELECTOR_TEXT_LENGTH) {
+        throw invalid(`${path} must be a bounded non-empty string.`, path);
+    }
+    if (screenPersistedString(value, "identity")) {
+        throw invalid(`${path} must not carry credential or request-URL shape.`, path);
+    }
+    return value;
+}
+function normalizeSelector(value) {
+    if (value === undefined)
+        return null;
+    const segments = Array.isArray(value) ? value : [value];
+    if (segments.length > MAX_SELECTOR_SEGMENTS)
+        throw invalid("selector exceeds its segment limit.", "selector");
+    return segments.map((segment, index) => {
+        const path = `selector[${index}]`;
+        if (typeof segment === "number") {
+            if (!Number.isSafeInteger(segment))
+                throw invalid(`${path} must be a safe integer.`, path);
+            return segment;
+        }
+        if (typeof segment !== "string" || segment.length === 0 || segment.length > MAX_SELECTOR_TEXT_LENGTH) {
+            throw invalid(`${path} must be a bounded non-empty string.`, path);
+        }
+        if (screenPersistedString(segment, "identity")) {
+            throw invalid(`${path} must not carry credential or request-URL shape.`, path);
+        }
+        return segment;
+    });
+}
+function emptyCanonicalQuery() {
+    return {
+        filter: null,
+        temporalFilter: null,
+        where: null,
+        spatialFilter: null,
+        outFields: null,
+        orderBy: null,
+        returnGeometry: null,
+        outSr: null,
+    };
+}
+function normalizePagination(value) {
+    if (value === undefined)
+        return { offset: 0 };
+    const record = plainRecord(value, "query.pagination");
+    for (const key in record) {
+        if (Object.hasOwn(record, key) && key !== "offset" && key !== "limit") {
+            throw invalid(`query.pagination.${key} is not supported.`, `query.pagination.${key}`);
+        }
+    }
+    const offset = record.offset === undefined ? 0 : nonNegativeInteger(record.offset, "query.pagination.offset");
+    if (record.limit === undefined)
+        return { offset };
+    return { offset, limit: nonNegativeInteger(record.limit, "query.pagination.limit") };
+}
+function normalizeOutFields(value) {
+    if (value === undefined)
+        return null;
+    if (!Array.isArray(value))
+        throw invalid("query.outFields must be an array.", "query.outFields");
+    const seen = new Set();
+    for (let index = 0; index < value.length; index += 1) {
+        const field = value[index];
+        if (typeof field !== "string" || field.trim().length === 0) {
+            throw invalid(`query.outFields[${index}] must be a non-empty string.`, `query.outFields[${index}]`);
+        }
+        seen.add(field.trim());
+    }
+    // Projection order carries no meaning, so a stable order keeps two callers
+    // that request the same fields on the same stored resource.
+    return [...seen].sort(compareCodeUnits);
+}
+function normalizeOrderBy(value) {
+    if (value === undefined)
+        return null;
+    if (!Array.isArray(value))
+        throw invalid("query.orderBy must be an array.", "query.orderBy");
+    return value.map((entry, index) => {
+        const path = `query.orderBy[${index}]`;
+        const record = plainRecord(entry, path);
+        for (const key in record) {
+            if (Object.hasOwn(record, key) && key !== "field" && key !== "direction") {
+                throw invalid(`${path}.${key} is not supported.`, `${path}.${key}`);
+            }
+        }
+        if (typeof record.field !== "string" || record.field.trim().length === 0) {
+            throw invalid(`${path}.field must be a non-empty string.`, `${path}.field`);
+        }
+        if (record.direction !== undefined && record.direction !== "asc" && record.direction !== "desc") {
+            throw invalid(`${path}.direction must be asc or desc.`, `${path}.direction`);
+        }
+        return { field: record.field.trim(), direction: record.direction ?? "asc" };
+    });
+}
+function normalizeOutSr(value) {
+    if (value === undefined)
+        return null;
+    if (typeof value === "number") {
+        if (!Number.isSafeInteger(value))
+            throw invalid("query.outSr must be a safe integer or string.", "query.outSr");
+        return value;
+    }
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw invalid("query.outSr must be a safe integer or non-empty string.", "query.outSr");
+    }
+    return value.trim();
+}
+function optionalText(value, path) {
+    if (value === undefined)
+        return null;
+    if (typeof value !== "string" || value.length === 0)
+        throw invalid(`${path} must be a non-empty string.`, path);
+    return value;
+}
+function requireBoolean(value, path) {
+    if (typeof value !== "boolean")
+        throw invalid(`${path} must be a boolean.`, path);
+    return value;
+}
+function nonNegativeInteger(value, path) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        throw invalid(`${path} must be a non-negative safe integer.`, path);
+    }
+    return value;
+}
+/** Detach an untrusted query member into plain JSON, refusing anything else. */
+function jsonValue(value, path, depth = 0) {
+    if (value === undefined)
+        return null;
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw invalid(`${path} must be finite.`, path);
+        return Object.is(value, -0) ? 0 : value;
+    }
+    if (depth >= MAX_QUERY_DEPTH)
+        throw invalid(`${path} exceeds the canonical nesting limit.`, path);
+    if (Array.isArray(value))
+        return value.map((entry, index) => jsonValue(entry, `${path}[${index}]`, depth + 1));
+    const record = plainRecord(value, path);
+    const out = {};
+    for (const key in record) {
+        if (!Object.hasOwn(record, key))
+            continue;
+        const child = record[key];
+        if (child === undefined)
+            continue;
+        out[key] = jsonValue(child, `${path}.${key}`, depth + 1);
+    }
+    return out;
+}
+function plainRecord(value, path) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw invalid(`${path} must be a plain object.`, path);
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        throw invalid(`${path} must be a plain object.`, path);
+    return value;
+}
+function invalid(message, path) {
+    return new HonuaOfflineRegionError("invalid-manifest", message, { path });
+}

package/offline/snapshot.d.ts

@@ -0,0 +1,132 @@
+import type { Query, Result } from "../contract/types.js";
+import type { HonuaFieldInfo, HonuaTypedFeature } from "../core/types.js";
+import { type OfflineRegionCanonicalQueryV1, type OfflineRegionResourceSelector, type OfflineRegionSelectionIdentityV1 } from "./selection.js";
+import { type OfflineRegionBounds, type OfflineRegionLimits, type OfflineRegionManifestV1, type OfflineRegionObservation, type OfflineRegionResourceKind, type OfflineRegionResourceLoader, type OfflineRegionValidator } from "./types.js";
+/**
+ * Snapshot planning: turn a protocol-neutral selection into a downloadable region.
+ *
+ * The planner is the missing producer between the contract and the region store.
+ * It takes a source identity, a canonical {@link Query}, a bounded extent, and the
+ * payloads an application already holds, and emits a manifest whose resource
+ * identities are deterministic functions of those inputs — never of a signed or
+ * token-bearing request URL. The same identity function answers the later read,
+ * so a snapshot and a read agree without persisting any addressing state.
+ *
+ * @experimental
+ */
+export declare const HONUA_OFFLINE_REGION_SNAPSHOT_KIND: "honua.offline-region-snapshot";
+export declare const HONUA_OFFLINE_REGION_SNAPSHOT_VERSION: "1.0";
+export declare const HONUA_OFFLINE_FEATURE_BATCH_KIND: "honua.offline-feature-batch";
+export declare const HONUA_OFFLINE_FEATURE_BATCH_VERSION: "1.0";
+/** Default ceiling on how many resources one planned snapshot may contain. */
+export declare const DEFAULT_OFFLINE_REGION_SNAPSHOT_MAX_CONTENTS = 10000;
+/**
+ * One stored answer to a canonical query.
+ *
+ * The envelope records the window it covers and whether more records existed, so
+ * a later read can tell the difference between "this is everything" and "this is
+ * the first page" without guessing.
+ */
+export interface OfflineRegionFeatureBatchV1<T = Record<string, unknown>> {
+    readonly kind: typeof HONUA_OFFLINE_FEATURE_BATCH_KIND;
+    readonly version: typeof HONUA_OFFLINE_FEATURE_BATCH_VERSION;
+    /** Window this batch covers, in the canonical query's own pagination terms. */
+    readonly pagination: {
+        readonly offset: number;
+        readonly limit?: number;
+    };
+    /** True when the source signalled that more records matched than were captured. */
+    readonly exceededTransferLimit: boolean;
+    readonly features: readonly HonuaTypedFeature<T>[];
+    readonly totalCount?: number;
+    readonly fields?: readonly HonuaFieldInfo[];
+}
+/** One payload contributed to a planned snapshot. */
+export interface OfflineRegionSnapshotContentV1 {
+    readonly kind: OfflineRegionResourceKind;
+    /** Exact bytes to persist. Tiles and assets stay opaque; nothing is re-encoded. */
+    readonly bytes: Uint8Array | ArrayBuffer;
+    readonly contentType?: string;
+    /** Discriminator when one selection stores several resources of one kind. */
+    readonly selector?: OfflineRegionResourceSelector;
+    readonly attributionIds?: readonly string[];
+}
+/** A source, a query, and a bounded extent, plus the payloads they require. */
+export interface OfflineRegionSnapshotSelectionV1 {
+    readonly name: string;
+    readonly sourceId: string;
+    /** Credentials and signed parameters are removed before anything is persisted. */
+    readonly endpoint: string | URL;
+    /** Opaque ACL/auth partition input. Only its digest is persisted or compared. */
+    readonly authorizationScopeFingerprint: string;
+    readonly bounds: OfflineRegionBounds;
+    readonly minZoom?: number;
+    readonly maxZoom?: number;
+    readonly sourceVersion: string;
+    readonly schemaVersion: string;
+    readonly planVersion: string;
+    readonly observation: OfflineRegionObservation;
+    readonly validator?: OfflineRegionValidator;
+    readonly expiresAt?: string;
+    readonly attribution?: Readonly<Record<string, string>>;
+    /** Protocol-neutral query this snapshot answers. Omitted means "no constraint". */
+    readonly query?: Query;
+    readonly contents: readonly OfflineRegionSnapshotContentV1[];
+    readonly limits?: OfflineRegionLimits & {
+        readonly maxContents?: number;
+    };
+}
+/** One planned resource: its deterministic identity and its verified payload size. */
+export interface OfflineRegionSnapshotEntryV1 {
+    readonly id: string;
+    readonly kind: OfflineRegionResourceKind;
+    readonly byteLength: number;
+    readonly integrity: `sha256:${string}`;
+    readonly contentType?: string;
+}
+/**
+ * A planned snapshot: the manifest to download plus the payloads it names.
+ *
+ * `payloads` is deliberately not part of the persisted contract — the manifest is
+ * the durable artifact. It exists so {@link createOfflineRegionSnapshotLoader}
+ * can serve the exact bytes the identities were computed from.
+ */
+export interface OfflineRegionSnapshotV1 {
+    readonly kind: typeof HONUA_OFFLINE_REGION_SNAPSHOT_KIND;
+    readonly version: typeof HONUA_OFFLINE_REGION_SNAPSHOT_VERSION;
+    readonly manifest: OfflineRegionManifestV1;
+    readonly selection: OfflineRegionSelectionIdentityV1;
+    readonly query: OfflineRegionCanonicalQueryV1;
+    readonly queryFingerprint: `sha256:${string}`;
+    readonly entries: readonly OfflineRegionSnapshotEntryV1[];
+    readonly payloads: ReadonlyMap<string, Uint8Array>;
+}
+/**
+ * Plan one bounded snapshot of a source, a query, and an extent.
+ *
+ * Every resource identity is derived from the selection — source identity,
+ * authorization-scope digest, captured versions, extent, canonical query, and the
+ * resource's own kind and selector. Identities are therefore stable across runs
+ * and processes, contain no request URL, and cannot collide across authorization
+ * scopes.
+ */
+export declare function planOfflineRegionSnapshot(selection: OfflineRegionSnapshotSelectionV1): Promise<OfflineRegionSnapshotV1>;
+/**
+ * Serve a planned snapshot's payloads to {@link downloadOfflineRegion}.
+ *
+ * The loader is offline by construction: it hands back the exact bytes the
+ * identities were computed from and refuses anything the plan does not name.
+ */
+export declare function createOfflineRegionSnapshotLoader(snapshot: OfflineRegionSnapshotV1): OfflineRegionResourceLoader;
+/** Capture a `Result` as the durable batch envelope a later read answers from. */
+export declare function createOfflineRegionFeatureBatch<T>(result: Pick<Result<T>, "features" | "exceededTransferLimit" | "totalCount" | "fields">, options?: {
+    readonly pagination?: {
+        readonly offset?: number;
+        readonly limit?: number;
+    };
+}): OfflineRegionFeatureBatchV1<T>;
+/** Encode a batch as the deterministic UTF-8 bytes the manifest pins. */
+export declare function encodeOfflineRegionFeatureBatch<T>(batch: OfflineRegionFeatureBatchV1<T>): Uint8Array;
+/** Decode and validate stored batch bytes. Anything unexpected fails closed. */
+export declare function decodeOfflineRegionFeatureBatch<T = Record<string, unknown>>(bytes: Uint8Array): OfflineRegionFeatureBatchV1<T>;
+//# sourceMappingURL=snapshot.d.ts.map