@honua/app-platform 0.1.12 → 0.1.14

package/columnar/geoarrow-reproject.d.ts

@@ -0,0 +1,22 @@
+import type { GeoArrowConversionLimits, GeoArrowPosition } from "./geoarrow-types.js";
+import type { ColumnarBatchIdentityV1 } from "./types.js";
+import type { ColumnarWorkerOperation } from "./worker.js";
+export interface CreateGeoArrowReprojectOperationOptions {
+    /** The CRS written to the output GeoArrow geometry metadata. */
+    readonly targetCrs: string | Readonly<Record<string, unknown>>;
+    /** The caller supplies the complete identity for the reprojected result. */
+    readonly identity: ColumnarBatchIdentityV1;
+    /** The schema identity must change when the CRS contract changes. */
+    readonly schemaId: string;
+    /** A host-owned CRS transform; it must return the same coordinate dimensionality. */
+    readonly project: (position: GeoArrowPosition) => GeoArrowPosition;
+    /** Additional conversion ceilings applied to both decode and encode. */
+    readonly limits?: GeoArrowConversionLimits;
+}
+/**
+ * Create a bounded worker operation for CRS reprojection of a GeoArrow batch.
+ * The SDK traverses and validates the normative geometry; CRS math remains
+ * host-owned so this path has no projection-library or network dependency.
+ */
+export declare function createGeoArrowReprojectOperation(options: CreateGeoArrowReprojectOperationOptions): ColumnarWorkerOperation;
+//# sourceMappingURL=geoarrow-reproject.d.ts.map

package/columnar/geoarrow-reproject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geoarrow-reproject.d.ts","sourceRoot":"","sources":["../../../src/columnar/geoarrow-reproject.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,wBAAwB,EAKxB,gBAAgB,EACjB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,uBAAuB,EAAmB,MAAM,YAAY,CAAC;AAC3E,OAAO,KAAK,EAAE,uBAAuB,EAAkC,MAAM,aAAa,CAAC;AAE3F,MAAM,WAAW,uCAAuC;IACtD,gEAAgE;IAChE,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC/D,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,CAAC;IAC3C,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qFAAqF;IACrF,QAAQ,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,gBAAgB,CAAC;IACnE,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE,wBAAwB,CAAC;CAC5C;AAiCD;;;;GAIG;AACH,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,uCAAuC,GAC/C,uBAAuB,CA4FzB"}

package/columnar/geoarrow-reproject.js

@@ -0,0 +1,119 @@
+import { createGeoArrowBatch, decodeGeoArrowBatch, inspectGeoArrowBatch } from "./geoarrow.js";
+function reprojectPosition(position, project) {
+    // GeoArrow represents an empty Point as an all-NaN position. It has no
+    // coordinates to transform, and passing it to a host projection would either
+    // reject it or turn the sentinel into a non-empty geometry.
+    if (position.every(Number.isNaN))
+        return position;
+    const result = project(position);
+    if (!Array.isArray(result) || result.length !== position.length) {
+        throw new TypeError("GeoArrow reprojection must preserve coordinate dimensionality.");
+    }
+    if (result.some((coordinate) => typeof coordinate !== "number" || !Number.isFinite(coordinate))) {
+        throw new TypeError("GeoArrow reprojection must return finite numeric coordinates.");
+    }
+    return result;
+}
+function reprojectGeometry(geometry, kind, project) {
+    if (geometry === null)
+        return null;
+    if (kind === "point")
+        return reprojectPosition(geometry, project);
+    if (kind === "linestring") {
+        return geometry.map((position) => reprojectPosition(position, project));
+    }
+    return geometry.map((ring) => ring.map((position) => reprojectPosition(position, project)));
+}
+/**
+ * Create a bounded worker operation for CRS reprojection of a GeoArrow batch.
+ * The SDK traverses and validates the normative geometry; CRS math remains
+ * host-owned so this path has no projection-library or network dependency.
+ */
+export function createGeoArrowReprojectOperation(options) {
+    if (typeof options.project !== "function")
+        throw new TypeError("project must be a function.");
+    const limits = options.limits ?? {};
+    return (batch, context) => {
+        context.signal.throwIfAborted();
+        context.reportProgress(0, "decode");
+        const inspection = inspectGeoArrowBatch(batch, limits);
+        const decoded = decodeGeoArrowBatch(batch, limits);
+        context.signal.throwIfAborted();
+        context.reportProgress(0.5, "reproject");
+        const values = decoded.rows.map((row) => reprojectGeometry(row.geometry, inspection.geometry.kind, options.project));
+        const geometry = inspection.geometry.kind === "point"
+            ? {
+                kind: "point",
+                field: inspection.geometry.field,
+                dimensions: inspection.geometry.dimensions,
+                coordinateLayout: inspection.geometry.coordinateLayout,
+                crs: options.targetCrs,
+                edges: inspection.geometry.edges,
+                values: values,
+            }
+            : inspection.geometry.kind === "linestring"
+                ? {
+                    kind: "linestring",
+                    field: inspection.geometry.field,
+                    dimensions: inspection.geometry.dimensions,
+                    coordinateLayout: inspection.geometry.coordinateLayout,
+                    crs: options.targetCrs,
+                    edges: inspection.geometry.edges,
+                    values: values,
+                }
+                : {
+                    kind: "polygon",
+                    field: inspection.geometry.field,
+                    dimensions: inspection.geometry.dimensions,
+                    coordinateLayout: inspection.geometry.coordinateLayout,
+                    crs: options.targetCrs,
+                    edges: inspection.geometry.edges,
+                    values: values,
+                };
+        const input = {
+            id: batch.id,
+            sequence: batch.sequence,
+            ...(batch.rowOffset === undefined ? {} : { rowOffset: batch.rowOffset }),
+            schemaId: options.schemaId,
+            identity: options.identity,
+            geometry,
+            ...(inspection.temporal
+                ? {
+                    temporal: {
+                        field: inspection.temporal.field,
+                        unit: inspection.temporal.unit,
+                        ...(inspection.temporal.timezone === undefined ? {} : { timezone: inspection.temporal.timezone }),
+                        values: decoded.rows.map((row) => row.timestamp ?? null),
+                    },
+                }
+                : {}),
+            ...(inspection.dictionary
+                ? {
+                    dictionary: {
+                        field: inspection.dictionary.field,
+                        ordered: inspection.dictionary.ordered,
+                        values: decoded.rows.map((row) => row.dictionaryValue ?? null),
+                    },
+                }
+                : {}),
+            ...(inspection.featureIds
+                ? {
+                    featureIds: {
+                        field: inspection.featureIds.field,
+                        values: decoded.rows.map((row) => row.featureId),
+                    },
+                }
+                : {}),
+        };
+        const result = createGeoArrowBatch(input, limits);
+        const output = inspection.dictionary?.ordered === true
+            ? {
+                ...result.batch,
+                buffers: result.batch.buffers.map((buffer) => batch.buffers.find((original) => original.id === buffer.id) ?? buffer),
+            }
+            : result.batch;
+        context.signal.throwIfAborted();
+        context.reportProgress(1, "complete");
+        return output;
+    };
+}

package/columnar/geoarrow-serialization.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Bounded, versioned persistence envelope for the normative GeoArrow mapping,
+ * plus the migration ladder that keeps a persisted cache readable across an
+ * envelope layout change (issue #940).
+ *
+ * Epic #394 requires that "persistent caches require versioned serialization
+ * and migration". Serialization landed first and pinned a single envelope
+ * version, so the moment the layout changed every persisted entry became
+ * permanently unreadable. The ladder here closes that: a stored envelope is
+ * migrated forward through an ordered registry of `fromVersion` → `toVersion`
+ * steps before it is validated, and the applied chain is reported in the
+ * deserialization metrics.
+ *
+ * Two properties are deliberate.
+ *
+ * 1. **Fail closed, before any payload is decoded.** Version resolution runs on
+ *    the parsed envelope header. An unknown, future, or unreachable version
+ *    throws `unsupported-serialization` with a stable message and no backing
+ *    buffer is ever base64-decoded.
+ * 2. **A migration cannot widen a caller's bounds.** A step receives only the
+ *    parsed envelope — never the caller's {@link GeoArrowSerializationOptions} —
+ *    and every ceiling is enforced against the migrated envelope, so migrating
+ *    an old entry can never admit more bytes than a fresh read would.
+ */
+import type { GeoArrowBatchSerializationResult, GeoArrowEnvelopeMigrationPlanV1, GeoArrowEnvelopeMigrationV1, GeoArrowSerializationOptions } from "./geoarrow-types.js";
+import type { ColumnarBatchV1 } from "./types.js";
+/** Stable discriminator for a persisted GeoArrow batch envelope. */
+export declare const HONUA_GEOARROW_ENVELOPE_KIND: "honua.geoarrow.batch";
+/**
+ * Envelope layout version written today.
+ *
+ * `1.1` adds the decoded `byteLength` of every backing and stamps the GeoArrow
+ * layout version, so backing ceilings are enforced before base64 is decoded
+ * rather than after a caller-sized allocation already happened.
+ */
+export declare const HONUA_GEOARROW_ENVELOPE_VERSION: "1.1";
+/**
+ * Ordered migration ladder applied on read, oldest step first.
+ *
+ * Every step is a pure structural rewrite of one parsed envelope. `1.0 → 1.1`
+ * derives each backing's decoded length from its base64 length — arithmetic on
+ * the encoded string, never a decode — and stamps the layout version that
+ * envelope 1.0 left implicit.
+ */
+export declare const GEOARROW_ENVELOPE_MIGRATIONS: readonly GeoArrowEnvelopeMigrationV1[];
+/**
+ * Resolve the ordered steps that carry `version` forward to `targetVersion`.
+ *
+ * Exported because a host that persists envelopes needs to answer "can this
+ * entry still be read?" without decoding it, and because the unreachable case —
+ * a ladder whose chain dead-ends before the target — has to be provable rather
+ * than assumed. The walk is bounded and cycle-safe: at most
+ * {@link MAX_MIGRATION_STEPS} steps, and no version is visited twice.
+ */
+export declare function planGeoArrowEnvelopeMigration(version: unknown, migrations?: readonly GeoArrowEnvelopeMigrationV1[], targetVersion?: string): GeoArrowEnvelopeMigrationPlanV1;
+/** Serialize one validated GeoArrow batch into a bounded, versioned persistence envelope. */
+export declare function serializeGeoArrowBatch(batch: ColumnarBatchV1, options?: GeoArrowSerializationOptions): Uint8Array;
+/**
+ * Report which envelope versions this build can still read.
+ *
+ * A store uses it to decide whether a persisted entry is worth keeping without
+ * decoding it, and a diagnostic uses it to explain why an entry was discarded.
+ */
+export declare function readableGeoArrowEnvelopeVersions(migrations?: readonly GeoArrowEnvelopeMigrationV1[]): readonly string[];
+/** Deserialize and revalidate a persisted GeoArrow envelope with explicit size ceilings. */
+export declare function deserializeGeoArrowBatch(input: Uint8Array | ArrayBuffer, options?: GeoArrowSerializationOptions): GeoArrowBatchSerializationResult;
+export type { GeoArrowBatchSerializationResult, GeoArrowSerializationMetrics } from "./geoarrow-types.js";
+//# sourceMappingURL=geoarrow-serialization.d.ts.map

package/columnar/geoarrow-serialization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geoarrow-serialization.d.ts","sourceRoot":"","sources":["../../../src/columnar/geoarrow-serialization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EACV,gCAAgC,EAChC,+BAA+B,EAC/B,2BAA2B,EAE3B,4BAA4B,EAC7B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAAE,eAAe,EAAsB,MAAM,YAAY,CAAC;AAEtE,oEAAoE;AACpE,eAAO,MAAM,4BAA4B,EAAG,sBAA+B,CAAC;AAE5E;;;;;;GAMG;AACH,eAAO,MAAM,+BAA+B,EAAG,KAAc,CAAC;AAiC9D;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,EAAE,SAAS,2BAA2B,EAiBnC,CAAC;AAmD7C;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,OAAO,EAChB,UAAU,GAAE,SAAS,2BAA2B,EAAiC,EACjF,aAAa,GAAE,MAA8B,GAC5C,+BAA+B,CAqCjC;AAgHD,6FAA6F;AAC7F,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,GAAE,4BAAiC,GAAG,UAAU,CA6CrH;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAC9C,UAAU,GAAE,SAAS,2BAA2B,EAAiC,GAChF,SAAS,MAAM,EAAE,CAMnB;AAED,4FAA4F;AAC5F,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,UAAU,GAAG,WAAW,EAC/B,OAAO,GAAE,4BAAiC,GACzC,gCAAgC,CAmDlC;AAED,YAAY,EAAE,gCAAgC,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC"}

package/columnar/geoarrow-serialization.js

@@ -0,0 +1,331 @@
+import { HonuaGeoArrowError as GeoArrowError, HONUA_GEOARROW_LAYOUT_VERSION } from "./geoarrow-types.js";
+import { inspectGeoArrowBatch } from "./geoarrow.js";
+/** Stable discriminator for a persisted GeoArrow batch envelope. */
+export const HONUA_GEOARROW_ENVELOPE_KIND = "honua.geoarrow.batch";
+/**
+ * Envelope layout version written today.
+ *
+ * `1.1` adds the decoded `byteLength` of every backing and stamps the GeoArrow
+ * layout version, so backing ceilings are enforced before base64 is decoded
+ * rather than after a caller-sized allocation already happened.
+ */
+export const HONUA_GEOARROW_ENVELOPE_VERSION = "1.1";
+const SERIALIZATION_KIND = HONUA_GEOARROW_ENVELOPE_KIND;
+const SERIALIZATION_VERSION = HONUA_GEOARROW_ENVELOPE_VERSION;
+const DEFAULT_MAX_SERIALIZED_BYTES = 128 * 1024 * 1024;
+const BASE64_CHUNK = 0x8000;
+/** Bound on ladder walks so a malformed or cyclic registry cannot spin. */
+const MAX_MIGRATION_STEPS = 16;
+/**
+ * Ordered migration ladder applied on read, oldest step first.
+ *
+ * Every step is a pure structural rewrite of one parsed envelope. `1.0 → 1.1`
+ * derives each backing's decoded length from its base64 length — arithmetic on
+ * the encoded string, never a decode — and stamps the layout version that
+ * envelope 1.0 left implicit.
+ */
+export const GEOARROW_ENVELOPE_MIGRATIONS = Object.freeze([
+    Object.freeze({
+        fromVersion: "1.0",
+        toVersion: "1.1",
+        migrate: (envelope) => {
+            const backings = Array.isArray(envelope.backings) ? envelope.backings : [];
+            return {
+                ...envelope,
+                version: "1.1",
+                layout: HONUA_GEOARROW_LAYOUT_VERSION,
+                backings: backings.map((backing) => {
+                    if (!isRecord(backing))
+                        return backing;
+                    return { ...backing, byteLength: base64DecodedLength(backing.data) };
+                }),
+            };
+        },
+    }),
+]);
+function fail(message, code) {
+    throw new GeoArrowError(code, message);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function toBase64(bytes) {
+    let binary = "";
+    for (let offset = 0; offset < bytes.length; offset += BASE64_CHUNK) {
+        binary += String.fromCharCode(...bytes.subarray(offset, Math.min(offset + BASE64_CHUNK, bytes.length)));
+    }
+    return btoa(binary);
+}
+function fromBase64(value, label) {
+    if (typeof value !== "string" || value.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) {
+        fail(`${label} must be valid base64.`, "invalid-batch");
+    }
+    let binary;
+    try {
+        binary = atob(value);
+    }
+    catch (cause) {
+        throw new GeoArrowError("invalid-batch", `${label} must be valid base64.`, undefined, { cause });
+    }
+    const result = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1)
+        result[index] = binary.charCodeAt(index);
+    return result;
+}
+function serializedLimit(options) {
+    const limit = options.maxSerializedBytes ?? DEFAULT_MAX_SERIALIZED_BYTES;
+    if (!Number.isSafeInteger(limit) || limit <= 0)
+        fail("maxSerializedBytes must be a positive safe integer.", "invalid-batch");
+    return limit;
+}
+function encodeEnvelope(envelope, limit) {
+    const bytes = new TextEncoder().encode(JSON.stringify(envelope));
+    if (bytes.byteLength > limit) {
+        fail(`GeoArrow envelope is ${bytes.byteLength} bytes; the limit is ${limit}.`, "serialization-limit-exceeded");
+    }
+    return bytes;
+}
+/**
+ * Resolve the ordered steps that carry `version` forward to `targetVersion`.
+ *
+ * Exported because a host that persists envelopes needs to answer "can this
+ * entry still be read?" without decoding it, and because the unreachable case —
+ * a ladder whose chain dead-ends before the target — has to be provable rather
+ * than assumed. The walk is bounded and cycle-safe: at most
+ * {@link MAX_MIGRATION_STEPS} steps, and no version is visited twice.
+ */
+export function planGeoArrowEnvelopeMigration(version, migrations = GEOARROW_ENVELOPE_MIGRATIONS, targetVersion = SERIALIZATION_VERSION) {
+    if (typeof version !== "string" || !isLayoutVersion(version)) {
+        return { applicable: false, reason: "unknown-version", detail: `"${String(version)}" is not a layout version.` };
+    }
+    if (version === targetVersion)
+        return { applicable: true, steps: Object.freeze([]), migrations: Object.freeze([]) };
+    const steps = [];
+    const applied = [];
+    const visited = new Set([version]);
+    let cursor = version;
+    while (steps.length < MAX_MIGRATION_STEPS) {
+        const step = migrations.find((candidate) => candidate.fromVersion === cursor);
+        if (!step)
+            break;
+        if (visited.has(step.toVersion))
+            break;
+        visited.add(step.toVersion);
+        steps.push(`${step.fromVersion}->${step.toVersion}`);
+        applied.push(step);
+        cursor = step.toVersion;
+        if (cursor === targetVersion) {
+            return { applicable: true, steps: Object.freeze(steps), migrations: Object.freeze(applied) };
+        }
+    }
+    // The walk stalled. A version the ladder has never heard of is unknown (or
+    // ahead of this build); one the ladder knows but cannot carry home is an
+    // unreachable path, and both refuse rather than guess at a layout.
+    const known = migrations.some((step) => step.fromVersion === version || step.toVersion === version);
+    if (steps.length > 0 || known) {
+        return {
+            applicable: false,
+            reason: "unreachable-version",
+            detail: `No migration path carries envelope version "${version}" to "${targetVersion}".`,
+        };
+    }
+    return {
+        applicable: false,
+        reason: compareLayoutVersions(version, targetVersion) > 0 ? "future-version" : "unknown-version",
+        detail: `Envelope version "${version}" has no migration to "${targetVersion}".`,
+    };
+}
+function readEnvelope(input, limit, migrations) {
+    const bytes = input instanceof Uint8Array ? input : new Uint8Array(input);
+    if (bytes.byteLength > limit) {
+        fail(`GeoArrow envelope is ${bytes.byteLength} bytes; the limit is ${limit}.`, "serialization-limit-exceeded");
+    }
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch (cause) {
+        throw new GeoArrowError("invalid-batch", "GeoArrow envelope must be valid UTF-8 JSON.", undefined, { cause });
+    }
+    if (!isRecord(value) || value.kind !== SERIALIZATION_KIND) {
+        fail(`Unsupported GeoArrow serialization kind "${String(isRecord(value) ? value.kind : undefined)}".`, "unsupported-serialization");
+    }
+    // Version resolution precedes every payload read: an envelope this build
+    // cannot carry forward is refused before a single backing is decoded.
+    const storedVersion = typeof value.version === "string" ? value.version : String(value.version);
+    const plan = planGeoArrowEnvelopeMigration(value.version, migrations);
+    if (!plan.applicable) {
+        fail(`Unsupported GeoArrow serialization version "${storedVersion}". ${plan.detail}`, "unsupported-serialization");
+    }
+    let migrated = value;
+    for (const step of plan.migrations) {
+        // A step sees only the envelope, never the caller's options, so no
+        // migration can widen a bound the caller set.
+        const next = step.migrate(Object.freeze({ ...migrated }));
+        if (!isRecord(next) || next.version !== step.toVersion) {
+            fail(`GeoArrow migration ${step.fromVersion}->${step.toVersion} did not produce a "${step.toVersion}" envelope.`, "unsupported-serialization");
+        }
+        migrated = next;
+    }
+    if (migrated.version !== SERIALIZATION_VERSION) {
+        // Defensive: the plan only resolves when its chain ends at the target and
+        // each step's output was verified above, so reaching here means a step
+        // rewrote the version underneath the ladder.
+        fail(`Unsupported GeoArrow serialization version "${storedVersion}"; migration did not reach "${SERIALIZATION_VERSION}".`, "unsupported-serialization");
+    }
+    if (migrated.layout !== HONUA_GEOARROW_LAYOUT_VERSION) {
+        // Envelope 1.0 carried no layout stamp, so its migration supplies this
+        // build's; a stamp that still disagrees came from a foreign layout and the
+        // buffers underneath it cannot be interpreted here.
+        fail(`Unsupported GeoArrow layout version "${String(migrated.layout)}"; this build reads "${HONUA_GEOARROW_LAYOUT_VERSION}".`, "unsupported-serialization");
+    }
+    if (!isRecord(migrated.batch) || !Array.isArray(migrated.batch.buffers) || !Array.isArray(migrated.backings)) {
+        fail("GeoArrow envelope is missing its batch or backing buffers.", "invalid-batch");
+    }
+    return {
+        envelope: migrated,
+        byteLength: bytes.byteLength,
+        applied: plan.steps,
+    };
+}
+function metrics(serializedBytes, batch, envelopeVersion, migrations) {
+    const seen = new Set();
+    for (const buffer of batch.buffers)
+        seen.add(buffer.data);
+    return Object.freeze({
+        serializedBytes,
+        backingBytes: [...seen].reduce((total, data) => total + data.byteLength, 0),
+        backingBuffers: seen.size,
+        envelopeVersion,
+        migrations: Object.freeze([...migrations]),
+    });
+}
+/** Layout versions are `<major>.<minor>` digit pairs; no regex, no backtracking. */
+function isLayoutVersion(value) {
+    const parts = value.split(".");
+    if (parts.length !== 2)
+        return false;
+    return parts.every((part) => part.length > 0 && part.length <= 6 && [...part].every((char) => char >= "0" && char <= "9"));
+}
+function compareLayoutVersions(left, right) {
+    const [leftMajor = 0, leftMinor = 0] = left.split(".").map(Number);
+    const [rightMajor = 0, rightMinor = 0] = right.split(".").map(Number);
+    if (leftMajor !== rightMajor)
+        return leftMajor < rightMajor ? -1 : 1;
+    if (leftMinor !== rightMinor)
+        return leftMinor < rightMinor ? -1 : 1;
+    return 0;
+}
+/** Decoded length of a base64 string, computed from its length and padding. */
+function base64DecodedLength(value) {
+    if (typeof value !== "string" || value.length % 4 !== 0)
+        return -1;
+    const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0;
+    return (value.length / 4) * 3 - padding;
+}
+/** Serialize one validated GeoArrow batch into a bounded, versioned persistence envelope. */
+export function serializeGeoArrowBatch(batch, options = {}) {
+    const limit = serializedLimit(options);
+    const inspection = inspectGeoArrowBatch(batch, options);
+    const backings = [];
+    const backingViews = [];
+    const backingIds = new Map();
+    const buffers = [];
+    for (const descriptor of inspection.batch.buffers) {
+        let backingId = backingIds.get(descriptor.data);
+        if (!backingId) {
+            backingId = `backing-${backings.length}`;
+            backingIds.set(descriptor.data, backingId);
+            backings.push({ id: backingId, byteLength: descriptor.data.byteLength, data: "" });
+            backingViews.push(new Uint8Array(descriptor.data));
+        }
+        buffers.push({
+            id: descriptor.id,
+            role: descriptor.role,
+            ...(descriptor.field === undefined ? {} : { field: descriptor.field }),
+            backingId,
+            byteOffset: descriptor.byteOffset,
+            byteLength: descriptor.byteLength,
+        });
+    }
+    const envelope = {
+        kind: SERIALIZATION_KIND,
+        version: SERIALIZATION_VERSION,
+        layout: HONUA_GEOARROW_LAYOUT_VERSION,
+        batch: { ...inspection.batch, buffers },
+        backings,
+    };
+    const base64Bytes = backingViews.reduce((total, bytes) => total + 4 * Math.ceil(bytes.byteLength / 3), 0);
+    const envelopeOverhead = new TextEncoder().encode(JSON.stringify({ ...envelope, backings: backings.map(({ id, byteLength }) => ({ id, byteLength, data: "" })) })).byteLength;
+    if (envelopeOverhead + base64Bytes > limit) {
+        fail(`GeoArrow envelope requires at least ${envelopeOverhead + base64Bytes} bytes; the limit is ${limit}.`, "serialization-limit-exceeded");
+    }
+    backings.forEach((backing, index) => {
+        backing.data = toBase64(backingViews[index]);
+    });
+    return encodeEnvelope(envelope, limit);
+}
+/**
+ * Report which envelope versions this build can still read.
+ *
+ * A store uses it to decide whether a persisted entry is worth keeping without
+ * decoding it, and a diagnostic uses it to explain why an entry was discarded.
+ */
+export function readableGeoArrowEnvelopeVersions(migrations = GEOARROW_ENVELOPE_MIGRATIONS) {
+    const versions = new Set([SERIALIZATION_VERSION]);
+    for (const step of migrations) {
+        if (planGeoArrowEnvelopeMigration(step.fromVersion, migrations).applicable)
+            versions.add(step.fromVersion);
+    }
+    return Object.freeze([...versions].sort());
+}
+/** Deserialize and revalidate a persisted GeoArrow envelope with explicit size ceilings. */
+export function deserializeGeoArrowBatch(input, options = {}) {
+    const limit = serializedLimit(options);
+    const { envelope, byteLength, applied } = readEnvelope(input, limit, options.migrations ?? GEOARROW_ENVELOPE_MIGRATIONS);
+    const backingMap = new Map();
+    let backingBytes = 0;
+    for (const backing of envelope.backings) {
+        if (!isRecord(backing) || typeof backing.id !== "string" || backingMap.has(backing.id)) {
+            fail("GeoArrow envelope contains an invalid or duplicate backing id.", "invalid-batch");
+        }
+        // Declared since envelope 1.1 and derived by the 1.0 migration, so the
+        // ceiling is enforced against the migrated envelope before any allocation.
+        const declared = backing.byteLength;
+        if (!Number.isSafeInteger(declared) || declared < 0) {
+            fail(`GeoArrow backing ${backing.id} does not declare a decoded byte length.`, "invalid-batch");
+        }
+        if (options.maxBackingBytes !== undefined && backingBytes + declared > options.maxBackingBytes) {
+            fail(`GeoArrow backings exceed the ${options.maxBackingBytes}-byte limit.`, "serialization-limit-exceeded");
+        }
+        const bytes = fromBase64(backing.data, `backing ${backing.id}`);
+        if (bytes.byteLength !== declared) {
+            fail(`GeoArrow backing ${backing.id} decoded to ${bytes.byteLength} bytes, not ${declared}.`, "invalid-batch");
+        }
+        backingBytes += bytes.byteLength;
+        backingMap.set(backing.id, bytes.buffer);
+    }
+    const serializedBatch = envelope.batch;
+    const buffers = serializedBatch.buffers.map((descriptor) => {
+        if (!isRecord(descriptor) || typeof descriptor.id !== "string" || typeof descriptor.backingId !== "string") {
+            fail("GeoArrow envelope contains an invalid buffer descriptor.", "invalid-batch");
+        }
+        const data = backingMap.get(descriptor.backingId);
+        if (!data)
+            fail(`GeoArrow buffer references unknown backing "${descriptor.backingId}".`, "invalid-batch");
+        return {
+            id: descriptor.id,
+            role: descriptor.role,
+            ...(descriptor.field === undefined ? {} : { field: descriptor.field }),
+            data,
+            byteOffset: descriptor.byteOffset,
+            byteLength: descriptor.byteLength,
+        };
+    });
+    const batch = { ...serializedBatch, buffers };
+    inspectGeoArrowBatch(batch, options);
+    return Object.freeze({
+        batch,
+        metrics: metrics(byteLength, batch, SERIALIZATION_VERSION, applied),
+    });
+}