@honua/app-platform 0.1.12 → 0.1.13

package/offline/quota.js

@@ -0,0 +1,370 @@
+import { HonuaOfflineRegionError } from "./types.js";
+/**
+ * Real browser storage-quota interrogation for offline-region admission.
+ *
+ * `logicalQuotaBytes` is an honest accounting of declared payload lengths, but
+ * it has no relationship to the space a browser will actually grant. This module
+ * closes that gap in the only way the platform supports: it reads
+ * `navigator.storage.estimate()` through an injectable interface, derives a
+ * conservative logical budget with an explicit reserve, and reports an explicit
+ * `unavailable` result rather than inventing a number when the platform cannot
+ * estimate.
+ *
+ * The estimate is deliberately imprecise and origin-scoped, and the accounting
+ * unit stays logical payload bytes: physical occupancy, deduplication, and index
+ * overhead are outside the contract and are exactly why a reserve exists. The
+ * derived budget is advisory, never a guarantee, so a device can still refuse a
+ * write that the budget admitted — which is why storage-pressure failures are
+ * classified here too.
+ *
+ * Nothing in this module performs network I/O, mutates the store, or reads or
+ * returns a credential, origin secret, or request URL. Persistence is never
+ * requested implicitly: `requestOfflinePersistentStorage()` is the only path to
+ * `navigator.storage.persist()` and it exists solely because the caller asked.
+ */
+/** Stable discriminator and version for storage-budget probe results. */
+export const HONUA_OFFLINE_STORAGE_BUDGET_KIND = "honua.offline-storage-budget";
+export const HONUA_OFFLINE_STORAGE_BUDGET_VERSION = "1.0";
+/** Stable discriminator and version for explicit persistence-request results. */
+export const HONUA_OFFLINE_STORAGE_PERSISTENCE_KIND = "honua.offline-storage-persistence";
+export const HONUA_OFFLINE_STORAGE_PERSISTENCE_VERSION = "1.0";
+/** Fraction of the remaining estimate held back from the derived logical budget. */
+export const DEFAULT_OFFLINE_STORAGE_HEADROOM_RATIO = 0.2;
+/** Floor for the reserve, so a large-quota origin still keeps real headroom. */
+export const DEFAULT_OFFLINE_STORAGE_MIN_RESERVE_BYTES = 16 * 1024 * 1024;
+const PROBE_OPTION_KEYS = new Set(["storage", "headroomRatio", "minimumReserveBytes", "now"]);
+const PERSIST_OPTION_KEYS = new Set(["storage"]);
+const BUDGET_KEYS = new Set([
+    "kind",
+    "version",
+    "status",
+    "observedAt",
+    "quotaBytes",
+    "usageBytes",
+    "remainingBytes",
+    "reserveBytes",
+    "headroomRatio",
+    "logicalBudgetBytes",
+    "persistence",
+    "reason",
+]);
+const PERSISTENCE_VALUES = new Set(["persisted", "best-effort", "unknown"]);
+const UNAVAILABLE_REASONS = new Set([
+    "storage-manager-unavailable",
+    "estimate-unsupported",
+    "estimate-failed",
+    "estimate-incomplete",
+]);
+/**
+ * Read the origin's real storage estimate and derive a conservative logical
+ * budget, or report explicitly that the platform cannot estimate.
+ *
+ * Performs no network I/O, writes nothing, and never calls
+ * `StorageManager.persist()`. `persisted()` is read when the platform offers it
+ * because persisted state changes the eviction risk of every cached region; a
+ * platform that does not offer it yields `persistence: "unknown"` rather than an
+ * assumption.
+ *
+ * Derivation is deterministic integer arithmetic over the reported values:
+ *
+ * ```text
+ * remaining = max(0, quota - usage)
+ * reserve   = min(remaining, max(minimumReserveBytes, floor(remaining * headroomRatio)))
+ * budget    = remaining - reserve
+ * ```
+ *
+ * so the budget can never exceed the platform-reported remaining quota, and a
+ * nearly full origin yields `0` instead of a number that cannot be honoured.
+ */
+export async function probeOfflineStorageBudget(options = {}) {
+    const record = plainRecord(options, "options");
+    allowedKeys(record, PROBE_OPTION_KEYS, "options");
+    const headroomRatio = normalizeRatio(record.headroomRatio, "options.headroomRatio");
+    const minimumReserveBytes = record.minimumReserveBytes === undefined
+        ? DEFAULT_OFFLINE_STORAGE_MIN_RESERVE_BYTES
+        : nonNegativeInteger(record.minimumReserveBytes, "options.minimumReserveBytes");
+    const nowMs = record.now === undefined ? Date.now() : validDate(record.now, "options.now");
+    const observedAt = new Date(nowMs).toISOString();
+    const storage = resolveStorageManager(record.storage, "options.storage");
+    if (!storage)
+        return unavailable(observedAt, "storage-manager-unavailable", "unknown");
+    const persistence = await readPersistence(storage);
+    if (typeof storage.estimate !== "function")
+        return unavailable(observedAt, "estimate-unsupported", persistence);
+    let estimate;
+    try {
+        estimate = await storage.estimate();
+    }
+    catch {
+        // An estimate that failed is not a budget of zero; it is no budget at all.
+        return unavailable(observedAt, "estimate-failed", persistence);
+    }
+    if (typeof estimate !== "object" || estimate === null) {
+        return unavailable(observedAt, "estimate-incomplete", persistence);
+    }
+    const quotaBytes = readByteCount(estimate.quota);
+    const usageBytes = readByteCount(estimate.usage);
+    if (quotaBytes === undefined || usageBytes === undefined) {
+        return unavailable(observedAt, "estimate-incomplete", persistence);
+    }
+    const remainingBytes = Math.max(0, quotaBytes - usageBytes);
+    const reserveBytes = Math.min(remainingBytes, Math.max(minimumReserveBytes, Math.floor(remainingBytes * headroomRatio)));
+    return deepFreeze({
+        kind: HONUA_OFFLINE_STORAGE_BUDGET_KIND,
+        version: HONUA_OFFLINE_STORAGE_BUDGET_VERSION,
+        status: "available",
+        observedAt,
+        quotaBytes,
+        usageBytes,
+        remainingBytes,
+        reserveBytes,
+        headroomRatio,
+        logicalBudgetBytes: remainingBytes - reserveBytes,
+        persistence,
+    });
+}
+/**
+ * Ask the browser to make this origin's storage persistent.
+ *
+ * This is the only call site of `StorageManager.persist()` in the SDK and it
+ * runs only because an application called it. It is never invoked by
+ * `downloadOfflineRegion`, by the probe, or by any store adapter: the request
+ * can show a permission prompt, and a download is not consent to ask.
+ */
+export async function requestOfflinePersistentStorage(options = {}) {
+    const record = plainRecord(options, "options");
+    allowedKeys(record, PERSIST_OPTION_KEYS, "options");
+    const storage = resolveStorageManager(record.storage, "options.storage");
+    if (!storage) {
+        return persistenceResult("unavailable", "unknown", "storage-manager-unavailable");
+    }
+    if (typeof storage.persist !== "function") {
+        return persistenceResult("unavailable", await readPersistence(storage), "persist-unsupported");
+    }
+    let granted;
+    try {
+        granted = (await storage.persist()) === true;
+    }
+    catch {
+        return persistenceResult("unavailable", await readPersistence(storage), "persist-failed");
+    }
+    return persistenceResult(granted ? "granted" : "denied", granted ? "persisted" : await readPersistence(storage));
+}
+const QUOTA_PRESSURE_NAMES = new Set(["QuotaExceededError", "NS_ERROR_DOM_QUOTA_REACHED", "QUOTA_EXCEEDED_ERR"]);
+const QUOTA_PRESSURE_LEGACY_CODES = new Set([22, 1014]);
+const MAX_CAUSE_NODES = 32;
+/**
+ * Report whether a thrown value is, or wraps, a platform storage-pressure
+ * failure — the device refusing a write for lack of space.
+ *
+ * Recognizes the `QuotaExceededError` `DOMException` every engine raises, the
+ * Firefox `NS_ERROR_DOM_QUOTA_REACHED` name, and the legacy numeric
+ * `DOMException` codes, then walks a bounded `cause` and `AggregateError` graph
+ * so a store adapter that wrapped the failure is still classified correctly.
+ * Bounded and cycle-safe: it inspects at most 32 nodes and visits none twice.
+ *
+ * Exported because a host-supplied `OfflineRegionStore` must classify the same
+ * condition the same way; without a shared predicate an adapter's wrapper would
+ * silently downgrade a full device to an internal store failure.
+ */
+export function isStorageQuotaPressureError(error) {
+    const pending = [error];
+    const seen = new Set();
+    let inspected = 0;
+    while (pending.length > 0 && inspected < MAX_CAUSE_NODES) {
+        const current = pending.shift();
+        if (typeof current !== "object" || current === null || seen.has(current))
+            continue;
+        seen.add(current);
+        inspected += 1;
+        if (isQuotaPressureShape(current))
+            return true;
+        const cause = readOwnOrInherited(current, "cause");
+        if (cause !== undefined)
+            pending.push(cause);
+        const errors = readOwnOrInherited(current, "errors");
+        if (Array.isArray(errors)) {
+            for (const nested of errors.slice(0, MAX_CAUSE_NODES))
+                pending.push(nested);
+        }
+    }
+    return false;
+}
+function isQuotaPressureShape(value) {
+    const name = readOwnOrInherited(value, "name");
+    if (typeof name === "string" && QUOTA_PRESSURE_NAMES.has(name))
+        return true;
+    const code = readOwnOrInherited(value, "code");
+    if (typeof code === "string" && QUOTA_PRESSURE_NAMES.has(code))
+        return true;
+    // Legacy numeric DOMException codes only count on a DOMException-shaped
+    // value; a bare `{ code: 22 }` from an unrelated API is not storage pressure.
+    return typeof code === "number" && typeof name === "string" && QUOTA_PRESSURE_LEGACY_CODES.has(code);
+}
+function readOwnOrInherited(value, key) {
+    try {
+        return value[key];
+    }
+    catch {
+        // A hostile getter must not be able to break failure classification.
+        return undefined;
+    }
+}
+/**
+ * Validate and take ownership of a caller-supplied budget envelope.
+ *
+ * Internal to the offline area: the diagnostic accepts a budget produced by
+ * `probeOfflineStorageBudget()`, and a public entry point cannot assume it was
+ * not hand-built.
+ */
+export function captureOfflineStorageBudget(value, path) {
+    const record = plainRecord(value, path);
+    allowedKeys(record, BUDGET_KEYS, path);
+    if (record.kind !== HONUA_OFFLINE_STORAGE_BUDGET_KIND)
+        invalid(`${path}.kind is unsupported.`, `${path}.kind`);
+    if (record.version !== HONUA_OFFLINE_STORAGE_BUDGET_VERSION) {
+        invalid(`${path}.version is unsupported.`, `${path}.version`);
+    }
+    const observedAt = normalizedTimestamp(record.observedAt, `${path}.observedAt`);
+    const persistence = memberOf(record.persistence, PERSISTENCE_VALUES, `${path}.persistence`);
+    if (record.status === "unavailable") {
+        return unavailable(observedAt, memberOf(record.reason, UNAVAILABLE_REASONS, `${path}.reason`), persistence);
+    }
+    if (record.status !== "available")
+        invalid(`${path}.status is invalid.`, `${path}.status`);
+    if (record.reason !== undefined)
+        invalid(`${path}.reason is not supported.`, `${path}.reason`);
+    const quotaBytes = nonNegativeInteger(record.quotaBytes, `${path}.quotaBytes`);
+    const usageBytes = nonNegativeInteger(record.usageBytes, `${path}.usageBytes`);
+    const remainingBytes = nonNegativeInteger(record.remainingBytes, `${path}.remainingBytes`);
+    const reserveBytes = nonNegativeInteger(record.reserveBytes, `${path}.reserveBytes`);
+    const logicalBudgetBytes = nonNegativeInteger(record.logicalBudgetBytes, `${path}.logicalBudgetBytes`);
+    const headroomRatio = normalizeRatio(record.headroomRatio, `${path}.headroomRatio`);
+    // The arithmetic identities are part of the contract, so a forged envelope
+    // cannot claim a budget larger than the remaining space it reports.
+    if (remainingBytes !== Math.max(0, quotaBytes - usageBytes) || reserveBytes > remainingBytes) {
+        invalid(`${path}.remainingBytes does not agree with the reported estimate.`, `${path}.remainingBytes`);
+    }
+    if (logicalBudgetBytes !== remainingBytes - reserveBytes) {
+        invalid(`${path}.logicalBudgetBytes does not agree with the reported reserve.`, `${path}.logicalBudgetBytes`);
+    }
+    return deepFreeze({
+        kind: HONUA_OFFLINE_STORAGE_BUDGET_KIND,
+        version: HONUA_OFFLINE_STORAGE_BUDGET_VERSION,
+        status: "available",
+        observedAt,
+        quotaBytes,
+        usageBytes,
+        remainingBytes,
+        reserveBytes,
+        headroomRatio,
+        logicalBudgetBytes,
+        persistence,
+    });
+}
+function resolveStorageManager(value, path) {
+    if (value === undefined) {
+        const platform = globalThis.navigator?.storage;
+        return typeof platform === "object" && platform !== null ? platform : undefined;
+    }
+    if (typeof value !== "object" || value === null)
+        invalid(`${path} must be a StorageManager-like object.`, path);
+    return value;
+}
+async function readPersistence(storage) {
+    if (typeof storage.persisted !== "function")
+        return "unknown";
+    try {
+        return (await storage.persisted()) === true ? "persisted" : "best-effort";
+    }
+    catch {
+        return "unknown";
+    }
+}
+function readByteCount(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+        return undefined;
+    const floored = Math.floor(value);
+    return Number.isSafeInteger(floored) ? floored : undefined;
+}
+function unavailable(observedAt, reason, persistence) {
+    return deepFreeze({
+        kind: HONUA_OFFLINE_STORAGE_BUDGET_KIND,
+        version: HONUA_OFFLINE_STORAGE_BUDGET_VERSION,
+        status: "unavailable",
+        observedAt,
+        reason,
+        persistence,
+    });
+}
+function persistenceResult(status, persistence, reason) {
+    return deepFreeze({
+        kind: HONUA_OFFLINE_STORAGE_PERSISTENCE_KIND,
+        version: HONUA_OFFLINE_STORAGE_PERSISTENCE_VERSION,
+        status,
+        persistence,
+        ...(reason === undefined ? {} : { reason }),
+    });
+}
+function plainRecord(value, path) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        invalid(`${path} must be a plain object.`, path);
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        invalid(`${path} must be a plain object.`, path);
+    if (Object.getOwnPropertySymbols(value).length > 0)
+        invalid(`${path} must not contain symbol properties.`, path);
+    return value;
+}
+function allowedKeys(record, allowed, path) {
+    for (const key in record) {
+        if (Object.hasOwn(record, key) && !allowed.has(key))
+            invalid(`${path}.${key} is not supported.`, `${path}.${key}`);
+    }
+}
+function memberOf(value, allowed, path) {
+    if (typeof value !== "string" || !allowed.has(value))
+        invalid(`${path} is invalid.`, path);
+    return value;
+}
+function normalizeRatio(value, path) {
+    if (value === undefined)
+        return DEFAULT_OFFLINE_STORAGE_HEADROOM_RATIO;
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
+        invalid(`${path} must be a finite ratio between 0 and 1.`, path);
+    }
+    return value;
+}
+function nonNegativeInteger(value, path) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        invalid(`${path} must be a non-negative safe integer.`, path);
+    }
+    return value;
+}
+function validDate(value, path) {
+    const time = value instanceof Date ? value.getTime() : Number.NaN;
+    if (!Number.isFinite(time))
+        invalid(`${path} must be a valid Date.`, path);
+    return time;
+}
+function normalizedTimestamp(value, path) {
+    if (typeof value !== "string" || value.length === 0)
+        invalid(`${path} must be an ISO-8601 timestamp.`, path);
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed) || new Date(parsed).toISOString() !== value) {
+        invalid(`${path} must be a normalized ISO-8601 timestamp.`, path);
+    }
+    return value;
+}
+function invalid(message, path) {
+    throw new HonuaOfflineRegionError("invalid-manifest", message, { path });
+}
+function deepFreeze(value) {
+    if (typeof value !== "object" || value === null || Object.isFrozen(value))
+        return value;
+    Object.freeze(value);
+    for (const child of Object.values(value))
+        deepFreeze(child);
+    return value;
+}

package/offline/read-gate.d.ts

@@ -0,0 +1,175 @@
+import type { Capability, DegradedReason, Query } from "../contract/types.js";
+import type { QueryPlanCacheOptions } from "../query-planner/types.js";
+import { type OfflineRegionResourceSelector, type OfflineRegionSelectionIdentityV1 } from "./selection.js";
+import { HonuaOfflineRegionError, type OfflineRegionBounds, type OfflineRegionManifestV1, type OfflineRegionObservation, type OfflineRegionResourceKind, type OfflineRegionResourceV1, type OfflineRegionStore, type OfflineRegionValidator } 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 declare const HONUA_OFFLINE_REGION_READ_KIND: "honua.offline-region-read";
+export declare const HONUA_OFFLINE_REGION_READ_VERSION: "1.0";
+/** Default age at which a region's observation is reported stale. */
+export declare const DEFAULT_OFFLINE_REGION_READ_STALE_AFTER_MS: number;
+export type OfflineRegionReadFreshness = "fresh" | "stale";
+/**
+ * What the persistent cache did, and why.
+ *
+ * `regionId` is the region manifest's own content digest, so anything served
+ * from storage is traceable to the exact snapshot identity that produced it.
+ */
+export interface OfflineRegionReadCacheDecisionV1 {
+    readonly kind: typeof HONUA_OFFLINE_REGION_READ_KIND;
+    readonly version: typeof HONUA_OFFLINE_REGION_READ_VERSION;
+    readonly policy: "prefer-cache";
+    readonly action: "reuse";
+    readonly state: "offline";
+    readonly freshness: OfflineRegionReadFreshness;
+    readonly completeness: "complete" | "partial";
+    readonly reason: "offline-entry" | "stale-entry";
+    /** Region manifest identity. Binds this answer to one snapshot. */
+    readonly regionId: `sha256:${string}`;
+    readonly queryFingerprint: `sha256:${string}`;
+    readonly authorizationScopeDigest: `sha256:${string}`;
+    readonly observedAt: string;
+    readonly ageMs: number;
+    readonly staleAfterMs: number;
+    /** Exactly which stored resources answered this read. */
+    readonly resources: readonly {
+        readonly id: string;
+        readonly kind: OfflineRegionResourceKind;
+        readonly byteLength: number;
+        readonly integrity: `sha256:${string}`;
+    }[];
+}
+/** Credential-free provenance travelling with anything served from storage. */
+export interface OfflineRegionReadProvenanceV1 {
+    readonly sourceId: string;
+    readonly endpoint: string;
+    readonly authorizationScopeDigest: `sha256:${string}`;
+    readonly sourceVersion: string;
+    readonly schemaVersion: string;
+    readonly planVersion: string;
+    readonly observation: OfflineRegionObservation;
+    readonly validator?: OfflineRegionValidator;
+}
+/**
+ * Inputs every offline read shares.
+ *
+ * A store is deliberately absent: admission is decided entirely from the
+ * manifest and the caller's own inputs, so the same options resolve a resource
+ * identity for a host's request matcher without any storage access at all.
+ */
+export interface OfflineRegionReadGateOptions {
+    /**
+     * The caller's current authorization-scope partition input. Its digest must
+     * equal the region's, so a scope change can never serve another principal's
+     * cached bytes.
+     */
+    readonly authorizationScopeFingerprint: string;
+    /**
+     * Protocol-neutral query the snapshot was planned with. Every resource of a
+     * snapshot is identified against its selection's canonical query, so a tile or
+     * document planned under a query must be read back under the same one.
+     */
+    readonly query?: Query;
+    /** Extent the caller is asking about. Must equal the region's own extent. */
+    readonly bounds?: OfflineRegionBounds;
+    /** Versions the caller expects. A drift fails closed instead of serving stale schema. */
+    readonly expect?: {
+        readonly sourceVersion?: string;
+        readonly schemaVersion?: string;
+        readonly planVersion?: string;
+    };
+    readonly now?: () => Date;
+    readonly staleAfterMs?: number;
+    readonly signal?: AbortSignal;
+}
+/** Gate inputs plus the store a read will resolve its identity against. */
+export interface OfflineRegionStoreReadOptions extends OfflineRegionReadGateOptions {
+    readonly store: OfflineRegionStore;
+}
+/** An admitted read: the region is verified, in scope, unexpired, and addressable. */
+export interface OfflineRegionReadGateV1 {
+    readonly manifest: OfflineRegionManifestV1;
+    readonly sourceId: string;
+    readonly authorizationScopeDigest: `sha256:${string}`;
+    readonly selection: OfflineRegionSelectionIdentityV1;
+    readonly queryFingerprint: `sha256:${string}`;
+    readonly pagination: {
+        readonly offset: number;
+        readonly limit?: number;
+    };
+    readonly now: Date;
+    readonly ageMs: number;
+    readonly staleAfterMs: number;
+    readonly freshness: OfflineRegionReadFreshness;
+}
+/**
+ * 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 declare function openOfflineRegionRead(inputManifest: OfflineRegionManifestV1, options: OfflineRegionReadGateOptions): Promise<OfflineRegionReadGateV1>;
+/** One verified stored payload plus the descriptor that vouched for it. */
+export interface OfflineRegionGatedResourceV1 {
+    readonly resource: OfflineRegionResourceV1;
+    readonly bytes: Uint8Array;
+}
+/**
+ * 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 declare function readGatedOfflineRegionResource(gate: OfflineRegionReadGateV1, options: {
+    readonly store: OfflineRegionStore;
+    readonly kind: OfflineRegionResourceKind;
+    readonly selector?: OfflineRegionResourceSelector;
+    readonly signal?: AbortSignal;
+}): Promise<OfflineRegionGatedResourceV1>;
+/** Report the persistent-cache decision for one admitted read. */
+export declare function createOfflineRegionReadCacheDecision(gate: OfflineRegionReadGateV1, resources: readonly OfflineRegionResourceV1[], completeness: "complete" | "partial"): OfflineRegionReadCacheDecisionV1;
+export declare function createOfflineRegionReadProvenance(gate: OfflineRegionReadGateV1): OfflineRegionReadProvenanceV1;
+/**
+ * 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 declare function offlineRegionCachedSnapshotDegradation(gate: OfflineRegionReadGateV1, capability: Capability): DegradedReason;
+/** Attribution for exactly the resources that answered a read. */
+export declare function pickOfflineRegionAttribution(manifest: OfflineRegionManifestV1, resources: readonly OfflineRegionResourceV1[]): Readonly<Record<string, string>>;
+/**
+ * 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 declare function createOfflineRegionQueryPlanCache(manifest: OfflineRegionManifestV1, options?: {
+    readonly now?: Date;
+    readonly staleAfterMs?: number;
+}): QueryPlanCacheOptions;
+export declare function assertExpectedVersion(expected: string | undefined, actual: string, path: string): void;
+export declare function normalizeStaleAfterMs(value: number | undefined): number;
+export declare function throwIfAborted(signal: AbortSignal | undefined): void;
+export declare function invalid(message: string, path: string): HonuaOfflineRegionError;
+/** Freeze a returned read. Typed arrays are caller-owned copies and stay writable. */
+export declare function deepFreezeRead<T>(value: T): T;
+//# sourceMappingURL=read-gate.d.ts.map

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

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