@bitbaum/geo-kit 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bitbaum
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,113 @@
-# Temporary Holding Version
+# `@bitbaum/geo-kit`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Country-neutral contracts for sharing versioned geography data across
+applications. The package owns no country packs, political claims, source
+choices, personal data, HTTP server, or rendering framework.
+
+## Install
+
+The Git repository is the install source until npm publishing is bootstrapped.
+Pin the reviewed v0.1.1 source commit for a reproducible install:
+
+```sh
+pnpm add github:bitbaum/geo-kit#a337aec928cf7804fecf459c308d366b90f4b2fa
+```
+
+The npm workflow uses npm Trusted Publishing and provenance. The first npm
+publish and publisher trust setup require a maintainer-held passkey; publishing
+stays disabled until that is complete.
+
+## Ownership
+
+- **Solon** is the authoritative owner of public places, source records,
+  historical assertions, decisions, and published boundary resources.
+- **OrangeCat** remains the owner of private residence and account data.
+- **Substrata and other clients** consume public, versioned data and choose the
+  layers they need. They do not copy Solon's geography database.
+- Application policy supplies accepted licences and controls whether a
+  proposal is approved. This package does not make that decision.
+
+## Data loading
+
+Publish a small manifest beside content-addressed GeoJSON or TopoJSON resources.
+Each resource identifies its source, geography, open-ended layer and level keys,
+validity period, optional map viewpoint, URL, SHA-256 digest, size and feature
+count. Resources can reference multiple sources, with each source's licence and
+attribution checked independently. Viewpoints have names, descriptions and
+source references, so a client can explain which representation it displays.
+A client asks for one or more
+geography/resource IDs, a date, and (when needed) a viewpoint. The default view
+includes only resources with no explicit viewpoint. `selectGeographyResources`
+rejects broad accidental loads by default and enforces byte/resource limits
+before any request is made.
+
+`loadGeographyResources` fetches selected same-origin URLs only, without cookies
+and without following redirects. It checks the decoded file size, SHA-256,
+GeoJSON/TopoJSON structure and feature count before returning parsed data. It
+accepts an injected cache, fetch implementation and abort signal so each app can
+use its own HTTP cache, IndexedDB policy and retry interface. Requests are
+bounded-concurrency and results use deterministic geography/kind/level/id order.
+
+`loadGeographyManifest` uses the same transport protections for the manifest,
+including a decoded byte limit enforced while streaming (64 KiB by default).
+An abort cancels a stalled body and also stops loads served from a cache.
+
+Resource selection can include a WGS84 `bbox` in west/south/east/north order.
+Only intersecting resources with known bounds are selected. Resources without
+bounds remain eligible, so missing metadata cannot silently hide coverage.
+West greater than east represents an antimeridian crossing. Geographic, time,
+viewpoint and download-budget selectors continue to apply together.
+
+```ts
+import { loadGeographyManifest, loadGeographyResources } from '@bitbaum/geo-kit';
+
+const controller = new AbortController();
+const options = {
+  baseUrl: window.location.origin,
+  licensePolicy: [{ spdx: 'CC0-1.0', requiresAttribution: false }],
+  signal: controller.signal, // AbortController owned by the application
+};
+const manifest = await loadGeographyManifest('/geography/manifest.json', options);
+const layers = await loadGeographyResources(manifest, {
+  geographyIds: ['selected-geography'],
+  asOf: '2026-09-30', // the date displayed by the application
+  levelKeys: ['subdivision'],
+  bbox: [7, 46, 9, 48],
+  maxBytes: 512 * 1024,
+}, options);
+```
+
+Layer keys and geographic IDs in this example come from the application's
+data. Country packs, detailed subdivision datasets and a border drawing UI are
+separate deliverables owned by the applications; this package does not invent
+or publish them.
+
+The library never reads the system clock. Pass the date displayed by the app to
+support historical maps deterministically. An explicit viewpoint is opt-in;
+the library does not treat any boundary representation as the default truth.
+
+## Assertions and proposed boundaries
+
+`AreaAssertion` follows Solon's sourced `claims`, `administers`, and `proposes`
+records. `summarizeAreaAssertions` filters those records by an explicit date and
+reports distinct claimants, administrators and proposers. Its `disputed` flag is
+a mechanical summary of competing claims or a mismatch between claimant and
+administrator; it is not a legal conclusion.
+
+`validateBoundaryDraft` checks a proposal's polygon, WGS84 coordinates, closed
+rings, input limits, source/license metadata and validity interval. Publication
+stays blocked until the consuming app provides both a full geometry-topology
+validator and an approval check for the draft's proposal. The draft contains a
+shape and its provenance only; claims about who owns or administers it are
+separate sourced assertions.
+
+## Verify
+
+```sh
+pnpm install --frozen-lockfile
+pnpm run verify
+```
+
+Runtime code has no dependencies and targets modern browsers plus Node.js 20 or
+later. The package ships JavaScript and declarations built from the TypeScript
+source, so consumers do not need a TypeScript-aware runtime loader.

package/dist/boundaries.d.ts

@@ -0,0 +1,4 @@
+import type { AreaAssertion, AreaPoliticalSummary, BoundaryDraft, BoundaryDraftValidation, BoundaryDraftValidationOptions, ISODate } from "./types.ts";
+export declare function summarizeAreaAssertions(areaId: string, assertions: readonly AreaAssertion[], asOf: ISODate): AreaPoliticalSummary;
+/** Validate a boundary submitted for a proposal; only the owning app can approve publication. */
+export declare function validateBoundaryDraft(draft: BoundaryDraft, options: BoundaryDraftValidationOptions): BoundaryDraftValidation;

package/dist/boundaries.js

@@ -0,0 +1,99 @@
+import { GeographyError } from "./errors.js";
+import { isISODate, isPlainObject, isStableKey, periodContains, validateAreaAssertions, validateGeometry, validPeriod, validUrl } from "./validation.js";
+export function summarizeAreaAssertions(areaId, assertions, asOf) {
+    if (!isISODate(asOf))
+        throw new GeographyError("invalid_manifest", "asOf must be a real ISO date");
+    const assertionProblems = validateAreaAssertions(assertions);
+    if (assertionProblems.length) {
+        throw new GeographyError("invalid_resource", assertionProblems.slice(0, 8).join("; "));
+    }
+    const current = assertions.filter((assertion) => assertion.areaId === areaId &&
+        periodContains(assertion.validFrom, assertion.validTo, asOf));
+    const unique = (kind) => [...new Set(current.filter((item) => item.assertion === kind).map((item) => item.jurisdictionId))].sort();
+    const claimants = unique("claims");
+    const administrators = unique("administers");
+    const proposers = unique("proposes");
+    return {
+        claimants,
+        administrators,
+        proposers,
+        disputed: claimants.length > 1 ||
+            (claimants.length === 1 && administrators.some((id) => id !== claimants[0])),
+        unclaimed: claimants.length === 0,
+    };
+}
+/** Validate a boundary submitted for a proposal; only the owning app can approve publication. */
+export function validateBoundaryDraft(draft, options) {
+    const problems = [];
+    if (!isStableKey(draft.id))
+        problems.push("draft id is invalid");
+    if (!isStableKey(draft.proposalId))
+        problems.push("proposalId is invalid");
+    if (!draft.title.trim())
+        problems.push("title is required");
+    if (!isStableKey(draft.geographyId) || !isStableKey(draft.kindKey)) {
+        problems.push("geographyId and kindKey must be stable keys");
+    }
+    if (!validPeriod(draft.validFrom, draft.validTo))
+        problems.push("validity period is invalid");
+    if (draft.geometry.type !== "Polygon" && draft.geometry.type !== "MultiPolygon") {
+        problems.push("a territory draft must be a Polygon or MultiPolygon");
+    }
+    const maxVertices = options.maxVertices ?? 100_000;
+    const geometryProblems = validateGeometry(draft.geometry, maxVertices);
+    problems.push(...geometryProblems);
+    const serialized = JSON.stringify(draft.geometry);
+    const byteSize = new TextEncoder().encode(serialized).byteLength;
+    const maxBytes = options.maxBytes ?? 5 * 1024 * 1024;
+    if (byteSize > maxBytes)
+        problems.push(`geometry is ${byteSize} bytes; limit is ${maxBytes}`);
+    const vertexCount = countPositions(draft.geometry);
+    const source = draft.source;
+    const rule = options.licensePolicy.find((candidate) => candidate.spdx === source.licenseSPDX);
+    if (!source.publisher.trim() || !source.dataset.trim() || !source.licenseSPDX.trim()) {
+        problems.push("boundary source needs a publisher, dataset, and license");
+    }
+    if (!rule) {
+        problems.push(`license ${source.licenseSPDX} is outside the supplied policy`);
+    }
+    else if (rule.requiresAttribution && !source.attribution?.trim()) {
+        problems.push(`license ${source.licenseSPDX} requires attribution`);
+    }
+    if (source.url && !validUrl(source.url, ["https:", "http:"]))
+        problems.push("source url must be HTTP(S)");
+    const topology = options.validateTopology?.(draft.geometry);
+    if (!options.validateTopology)
+        problems.push("a full topology validator is required before publication");
+    else if (!topology?.valid)
+        problems.push(...(topology?.problems?.length ? topology.problems : ["geometry topology is invalid"]));
+    if (!options.proposalApproved)
+        problems.push("the app must verify the proposal is approved before publication");
+    else if (!options.proposalApproved(draft.proposalId))
+        problems.push("proposal is not approved for publication");
+    return {
+        problems,
+        publishable: problems.length === 0,
+        vertexCount,
+        byteSize,
+    };
+}
+function countPositions(value) {
+    let count = 0;
+    const visit = (part) => {
+        if (!Array.isArray(part))
+            return;
+        if (part.length >= 2 && part.every((coordinate) => typeof coordinate === "number")) {
+            count += 1;
+            return;
+        }
+        for (const child of part)
+            visit(child);
+    };
+    if (isPlainObject(value)) {
+        if ("coordinates" in value)
+            visit(value.coordinates);
+        if (Array.isArray(value.geometries))
+            value.geometries.forEach(visit);
+    }
+    return count;
+}

package/dist/errors.d.ts

@@ -0,0 +1,4 @@
+export declare class GeographyError extends Error {
+    readonly code: "invalid_manifest" | "selection_required" | "selection_limit" | "invalid_resource" | "resource_fetch_failed" | "resource_too_large" | "invalid_boundary_draft";
+    constructor(code: "invalid_manifest" | "selection_required" | "selection_limit" | "invalid_resource" | "resource_fetch_failed" | "resource_too_large" | "invalid_boundary_draft", message: string);
+}

package/dist/errors.js

@@ -0,0 +1,8 @@
+export class GeographyError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "GeographyError";
+    }
+}

package/dist/http.d.ts

@@ -0,0 +1,6 @@
+import type { LoadResourcesOptions } from "./types.ts";
+type FetchOptions = Pick<LoadResourcesOptions, "baseUrl" | "signal" | "fetcher">;
+export declare function publicDataUrl(href: string, baseUrl: string): URL;
+/** Shared bounded transport for manifests and geometry, including decoded compressed bodies. */
+export declare function fetchGeographyBytes(href: string, maxBytes: number, options: FetchOptions, label: string): Promise<Uint8Array>;
+export {};

package/dist/http.js

@@ -0,0 +1,93 @@
+import { GeographyError } from "./errors.js";
+import { safeResourceHref } from "./validation.js";
+export function publicDataUrl(href, baseUrl) {
+    try {
+        const base = new URL(baseUrl);
+        if (!safeResourceHref(href) || !["https:", "http:"].includes(base.protocol) || base.username || base.password) {
+            throw new Error("unsafe geography URL");
+        }
+        const url = new URL(href, base);
+        if (url.origin !== base.origin)
+            throw new Error("off-origin geography URL");
+        return url;
+    }
+    catch {
+        throw new GeographyError("invalid_manifest", "geography URLs must be safe root-relative paths on an HTTP(S) baseUrl");
+    }
+}
+/** Shared bounded transport for manifests and geometry, including decoded compressed bodies. */
+export async function fetchGeographyBytes(href, maxBytes, options, label) {
+    options.signal?.throwIfAborted();
+    const url = publicDataUrl(href, options.baseUrl);
+    let response;
+    try {
+        response = await (options.fetcher ?? fetch)(url, {
+            method: "GET",
+            credentials: "omit",
+            redirect: "error",
+            signal: options.signal,
+            headers: { accept: "application/geo+json, application/json" },
+        });
+    }
+    catch (error) {
+        if (options.signal?.aborted)
+            throw options.signal.reason ?? error;
+        throw new GeographyError("resource_fetch_failed", `${label} could not be fetched`);
+    }
+    if (options.signal?.aborted) {
+        await response.body?.cancel(options.signal.reason).catch(() => undefined);
+        options.signal.throwIfAborted();
+    }
+    if (!response.ok) {
+        await response.body?.cancel("HTTP error").catch(() => undefined);
+        throw new GeographyError("resource_fetch_failed", `${label} returned HTTP ${response.status}`);
+    }
+    const contentLength = response.headers.get("content-length");
+    const contentEncoding = response.headers.get("content-encoding");
+    if ((!contentEncoding || contentEncoding === "identity") && contentLength && /^\d+$/.test(contentLength) && Number(contentLength) > maxBytes) {
+        await response.body?.cancel("declared size exceeded").catch(() => undefined);
+        throw new GeographyError("resource_too_large", `${label} exceeded its byte limit`);
+    }
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new GeographyError("resource_fetch_failed", `${label} has no response body`);
+    const chunks = [];
+    let size = 0;
+    const onAbort = () => { void reader.cancel(options.signal?.reason).catch(() => undefined); };
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+        options.signal?.throwIfAborted();
+        while (true) {
+            const { done, value } = await reader.read();
+            options.signal?.throwIfAborted();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            size += value.byteLength;
+            if (size > maxBytes) {
+                await reader.cancel("declared size exceeded").catch(() => undefined);
+                throw new GeographyError("resource_too_large", `${label} exceeded its byte limit`);
+            }
+            chunks.push(value);
+        }
+    }
+    catch (error) {
+        if (options.signal?.aborted)
+            throw options.signal.reason ?? error;
+        if (error instanceof GeographyError)
+            throw error;
+        throw new GeographyError("resource_fetch_failed", `${label} body could not be read`);
+    }
+    finally {
+        options.signal?.removeEventListener("abort", onAbort);
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/** Public entry point for the country-neutral geography contract and helpers. */
+export * from "./types.ts";
+export { GeographyError } from "./errors.ts";
+export { isISODate, isWgs84Position, validateAreaAssertions, validateGeographyManifest, validateGeometry } from "./validation.ts";
+export { loadGeographyResources, makeGeometryRef, selectGeographyResources, sha256Hex, verifyGeographyResource } from "./resources.ts";
+export { summarizeAreaAssertions, validateBoundaryDraft } from "./boundaries.ts";
+export { loadGeographyManifest } from "./manifests.ts";
+export { isWgs84Bounds, intersectsGeographyBounds } from "./spatial.ts";

package/dist/index.js

@@ -0,0 +1,8 @@
+/** Public entry point for the country-neutral geography contract and helpers. */
+export * from "./types.js";
+export { GeographyError } from "./errors.js";
+export { isISODate, isWgs84Position, validateAreaAssertions, validateGeographyManifest, validateGeometry } from "./validation.js";
+export { loadGeographyResources, makeGeometryRef, selectGeographyResources, sha256Hex, verifyGeographyResource } from "./resources.js";
+export { summarizeAreaAssertions, validateBoundaryDraft } from "./boundaries.js";
+export { loadGeographyManifest } from "./manifests.js";
+export { isWgs84Bounds, intersectsGeographyBounds } from "./spatial.js";

package/dist/manifests.d.ts

@@ -0,0 +1,3 @@
+import type { GeographyManifest, LoadManifestOptions } from "./types.ts";
+/** Fetch a public manifest within a byte budget, then validate its provenance and policy. */
+export declare function loadGeographyManifest(href: string, options: LoadManifestOptions): Promise<GeographyManifest>;

package/dist/manifests.js

@@ -0,0 +1,22 @@
+import { GeographyError } from "./errors.js";
+import { fetchGeographyBytes } from "./http.js";
+import { validateGeographyManifest } from "./validation.js";
+/** Fetch a public manifest within a byte budget, then validate its provenance and policy. */
+export async function loadGeographyManifest(href, options) {
+    const maxBytes = options.maxBytes ?? 64 * 1024;
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+        throw new GeographyError("invalid_manifest", "manifest maxBytes must be a positive safe integer");
+    }
+    const bytes = await fetchGeographyBytes(href, maxBytes, options, "geography manifest");
+    let manifest;
+    try {
+        manifest = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        throw new GeographyError("invalid_manifest", "geography manifest is not valid UTF-8 JSON");
+    }
+    const problems = validateGeographyManifest(manifest, options);
+    if (problems.length)
+        throw new GeographyError("invalid_manifest", problems.slice(0, 8).join("; "));
+    return manifest;
+}

package/dist/resources.d.ts

@@ -0,0 +1,14 @@
+import type { GeographyManifest, GeographyResource, GeometryResourceData, LoadedResource, LoadResourcesOptions, ResourceSelection } from "./types.ts";
+export declare function selectGeographyResources(manifest: GeographyManifest, request: ResourceSelection): GeographyResource[];
+/** Verify the declared digest, exact decoded size, JSON shape, and feature count. */
+export declare function verifyGeographyResource(resource: GeographyResource, bytes: Uint8Array): Promise<GeometryResourceData>;
+export declare function sha256Hex(bytes: Uint8Array): Promise<string>;
+/** Fetches selected public data without cookies; data resources may not redirect off-origin. */
+export declare function loadGeographyResources(manifest: GeographyManifest, request: ResourceSelection, options: LoadResourcesOptions): Promise<LoadedResource[]>;
+/** Build an opaque, versioned geometry reference suitable for Solon's `areas.geometry_ref`. */
+export declare function makeGeometryRef(input: {
+    sourceId: string;
+    datasetVersion: string;
+    resourceId: string;
+    featureId: string | number;
+}): string;