@honua/mcp-server 0.1.1-beta.0 → 0.1.4-beta.0

package/dist/src/neutral/query.d.ts

@@ -0,0 +1,101 @@
+import type { Query, SortSpec } from "@honua/sdk-js/contract";
+import { z } from "zod";
+import { GEOMETRY_TYPES } from "../helpers.js";
+import { SPATIAL_PREDICATES, temporalSchema } from "./filter.js";
+/**
+ * PROTOCOL-NEUTRAL query vocabulary for the MCP tool contract (#1005).
+ *
+ * Everything here lowers onto the SDK's stable `Query` envelope, which each
+ * protocol adapter translates into its own dialect. Nothing in the vocabulary
+ * is Esri-shaped: the filter is the typed semantic filter, geometry is GeoJSON
+ * (or a bbox), the spatial predicate is the neutral one, sorting is
+ * `field`/`direction`, and paging is `limit`/`offset`.
+ *
+ * Two deprecated compatibility inputs remain so existing clients keep working:
+ * `where` (source-native filter text, whose language depends on the backend)
+ * and `geometryType` (an Esri geometry-type tag for Esri-JSON geometry). Both
+ * are optional; neither is required by any tool.
+ */
+/** Filter + spatial + temporal fields shared by every query-family tool. */
+export declare const queryFilterFields: {
+    readonly filter: z.ZodOptional<z.ZodType<import("./filter.js").FilterNode, z.ZodTypeDef, import("./filter.js").FilterNode>>;
+    readonly where: z.ZodOptional<z.ZodString>;
+    readonly bbox: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+    readonly bboxSrid: z.ZodOptional<z.ZodNumber>;
+    readonly geometry: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    readonly geometryType: z.ZodOptional<z.ZodEnum<["esriGeometryPoint", "esriGeometryPolyline", "esriGeometryPolygon", "esriGeometryEnvelope", "esriGeometryMultipoint"]>>;
+    readonly spatialRel: z.ZodOptional<z.ZodEnum<["intersects", "contains", "within", "crosses", "touches", "overlaps", "bbox-intersects"]>>;
+    readonly temporal: z.ZodOptional<z.ZodObject<{
+        instant: z.ZodOptional<z.ZodString>;
+        start: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        end: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        field: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        field?: string | undefined;
+        instant?: string | undefined;
+        start?: string | null | undefined;
+        end?: string | null | undefined;
+    }, {
+        field?: string | undefined;
+        instant?: string | undefined;
+        start?: string | null | undefined;
+        end?: string | null | undefined;
+    }>>;
+};
+/** Projection / ordering / paging fields for the feature-returning tools. */
+export declare const queryShapeFields: {
+    readonly outFields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    readonly orderBy: z.ZodOptional<z.ZodUnion<[z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        direction: z.ZodOptional<z.ZodEnum<["asc", "desc"]>>;
+    }, "strip", z.ZodTypeAny, {
+        field: string;
+        direction?: "asc" | "desc" | undefined;
+    }, {
+        field: string;
+        direction?: "asc" | "desc" | undefined;
+    }>, "many">, z.ZodString]>>;
+    readonly limit: z.ZodOptional<z.ZodNumber>;
+    readonly offset: z.ZodOptional<z.ZodNumber>;
+    readonly returnGeometry: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    readonly geometryFormat: z.ZodOptional<z.ZodEnum<["geojson", "esri-json"]>>;
+    readonly outSr: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+};
+export interface NeutralQueryInput {
+    filter?: unknown;
+    where?: string | undefined;
+    bbox?: number[] | undefined;
+    bboxSrid?: number | undefined;
+    geometry?: Record<string, unknown> | undefined;
+    geometryType?: (typeof GEOMETRY_TYPES)[number] | undefined;
+    spatialRel?: (typeof SPATIAL_PREDICATES)[number] | undefined;
+    temporal?: z.infer<typeof temporalSchema> | undefined;
+    outFields?: string[] | undefined;
+    orderBy?: string | {
+        field: string;
+        direction?: "asc" | "desc";
+    }[] | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    returnGeometry?: boolean | undefined;
+    outSr?: string | number | undefined;
+}
+/** Parse the legacy `"NAME DESC,VALUE ASC"` order string into canonical sort specs. */
+export declare function parseOrderBy(orderBy: NeutralQueryInput["orderBy"]): SortSpec[] | undefined;
+export interface ToQueryOptions {
+    /** Protocol of the resolved source; drives protocol-quirk compensation only. */
+    readonly protocol: string;
+    /** Apply the default page size / cap. Off for aggregate + extent queries. */
+    readonly paginate?: boolean;
+}
+/**
+ * Lower the neutral tool input onto the SDK's canonical `Query`.
+ *
+ * The one protocol-specific compensation is `outFields`: a GeoServices
+ * `query` with no `outFields` returns OBJECTID only, whereas every other
+ * protocol returns all properties. Requesting `*` for the GeoServices family
+ * keeps "omit outFields ⇒ all fields" true across protocols rather than
+ * leaking an Esri default into the neutral contract.
+ */
+export declare function toQuery(input: NeutralQueryInput, options: ToQueryOptions): Query;
+//# sourceMappingURL=query.d.ts.map

package/dist/src/neutral/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../src/neutral/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAyB,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACrF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,cAAc,EAAc,MAAM,eAAe,CAAC;AAC3D,OAAO,EAEL,kBAAkB,EAKlB,cAAc,EAIf,MAAM,aAAa,CAAC;AAGrB;;;;;;;;;;;;;GAaG;AAEH,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;CA4BpB,CAAC;AAOX,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;CAmBnB,CAAC;AAEX,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC/C,YAAY,CAAC,EAAE,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IAC3D,UAAU,CAAC,EAAE,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IAC7D,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,GAAG,SAAS,CAAC;IACtD,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;KAAE,EAAE,GAAG,SAAS,CAAC;IAC/E,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,cAAc,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACrC;AAED,uFAAuF;AACvF,wBAAgB,YAAY,CAAC,OAAO,EAAE,iBAAiB,CAAC,SAAS,CAAC,GAAG,QAAQ,EAAE,GAAG,SAAS,CAmB1F;AA2CD,MAAM,WAAW,cAAc;IAC7B,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,cAAc,GAAG,KAAK,CAwChF"}

package/dist/src/neutral/query.js

@@ -0,0 +1,180 @@
+import { z } from "zod";
+import { GEOMETRY_TYPES, clampLimit } from "../helpers.js";
+import { FilterInputError, SPATIAL_PREDICATES, andFilters, bboxToOperand, filterSchema, geometrySchema, temporalSchema, toGeometryOperand, toQueryFilter, toTemporalFilter, } from "./filter.js";
+import { isGeoServicesProtocol } from "./source-ref.js";
+/**
+ * PROTOCOL-NEUTRAL query vocabulary for the MCP tool contract (#1005).
+ *
+ * Everything here lowers onto the SDK's stable `Query` envelope, which each
+ * protocol adapter translates into its own dialect. Nothing in the vocabulary
+ * is Esri-shaped: the filter is the typed semantic filter, geometry is GeoJSON
+ * (or a bbox), the spatial predicate is the neutral one, sorting is
+ * `field`/`direction`, and paging is `limit`/`offset`.
+ *
+ * Two deprecated compatibility inputs remain so existing clients keep working:
+ * `where` (source-native filter text, whose language depends on the backend)
+ * and `geometryType` (an Esri geometry-type tag for Esri-JSON geometry). Both
+ * are optional; neither is required by any tool.
+ */
+/** Filter + spatial + temporal fields shared by every query-family tool. */
+export const queryFilterFields = {
+    filter: filterSchema
+        .optional()
+        .describe('Typed, protocol-neutral filter. Nodes are {"op": …}: comparison (eq/ne/lt/lte/gt/gte with field+value), in (field+values), between (field+lower+upper), is-null/is-not-null (field), like (field+pattern[+caseSensitive]), and/or (args), not (arg), spatial (intersects/contains/within/crosses/touches/overlaps/bbox-intersects with geometry or bbox), temporal (before/after/during/time-intersects with field+value). Compiles to SQL-92, CQL2, FES 2.0, or OData depending on the backend, and fails with a named capability error rather than silently dropping a construct.'),
+    where: z
+        .string()
+        .optional()
+        .describe("[DEPRECATED — use `filter`] Source-native filter text. Its language depends on the backend (GeoServices SQL-92, CQL2, OData); it is not protocol neutral."),
+    bbox: z.array(z.number()).length(4).optional().describe("Spatial filter envelope [minX, minY, maxX, maxY]."),
+    bboxSrid: z.number().int().optional().describe("Spatial reference (SRID/WKID) of the bbox ordinates (default 4326)."),
+    geometry: geometrySchema
+        .optional()
+        .describe("Spatial filter geometry as GeoJSON (RFC 7946). Esri-JSON geometry is still accepted for compatibility and is converted on the way in."),
+    geometryType: z
+        .enum(GEOMETRY_TYPES)
+        .optional()
+        .describe("[DEPRECATED — send GeoJSON] Esri geometry type tag, used only to disambiguate Esri-JSON geometry."),
+    spatialRel: z
+        .enum(SPATIAL_PREDICATES)
+        .optional()
+        .describe("Protocol-neutral spatial predicate applied to `geometry`/`bbox` (default: intersects)."),
+    temporal: temporalSchema.optional(),
+};
+const sortSpecSchema = z.object({
+    field: z.string().min(1),
+    direction: z.enum(["asc", "desc"]).optional(),
+});
+/** Projection / ordering / paging fields for the feature-returning tools. */
+export const queryShapeFields = {
+    outFields: z.array(z.string()).optional().describe("Fields to return; defaults to all."),
+    orderBy: z
+        .union([z.array(sortSpecSchema), z.string()])
+        .optional()
+        .describe('Sort order as [{"field":"NAME","direction":"desc"}], or the legacy string form "NAME DESC,VALUE ASC".'),
+    limit: z.number().int().positive().optional().describe("Max features to return (default 100, max 2000)."),
+    offset: z.number().int().nonnegative().optional().describe("Number of features to skip (for pagination)."),
+    returnGeometry: z.boolean().optional().default(false).describe("Include geometry in results (default: false)."),
+    geometryFormat: z
+        .enum(["geojson", "esri-json"])
+        .optional()
+        .describe("Geometry encoding of returned features. Defaults to `geojson` for neutrally addressed sources, and to `esri-json` when the deprecated serviceId/layerId pair was used (preserving legacy client output)."),
+    outSr: z
+        .union([z.string(), z.number()])
+        .optional()
+        .describe("Output spatial reference (WKID or CRS identifier) for returned geometry."),
+};
+/** Parse the legacy `"NAME DESC,VALUE ASC"` order string into canonical sort specs. */
+export function parseOrderBy(orderBy) {
+    if (orderBy === undefined)
+        return undefined;
+    if (Array.isArray(orderBy)) {
+        return orderBy.length > 0
+            ? orderBy.map((spec) => ({ field: spec.field, direction: spec.direction ?? "asc" }))
+            : undefined;
+    }
+    const specs = orderBy
+        .split(",")
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0)
+        .map((part) => {
+        const [field, direction] = part.split(/\s+/);
+        return {
+            field,
+            direction: (direction ?? "asc").toLowerCase() === "desc" ? "desc" : "asc",
+        };
+    });
+    return specs.length > 0 ? specs : undefined;
+}
+/**
+ * Lower the spatial constraint onto whichever canonical channel the widest set
+ * of protocols can serve.
+ *
+ * An envelope tested with `intersects` is the one spatial constraint every
+ * protocol expresses natively — it is the OGC API Features / STAC `bbox`
+ * parameter (Part 1, no filtering extension required) and a plain GeoServices
+ * geometry parameter — so it travels as `Query.spatialFilter`. Anything richer
+ * (a real polygon, `within`, `crosses`, …) becomes a typed spatial filter node,
+ * which compiles to CQL2 / FES / SQL-92 where supported and fails closed,
+ * naming the construct, where it is not.
+ */
+function spatialConstraint(input) {
+    if (input.geometry && input.bbox) {
+        throw new FilterInputError("Pass either `geometry` or `bbox` for the spatial filter, not both.");
+    }
+    const operand = input.bbox
+        ? bboxToOperand(input.bbox, input.bboxSrid)
+        : input.geometry
+            ? toGeometryOperand(input.geometry, input.geometryType, input.bboxSrid)
+            : undefined;
+    if (!operand)
+        return {};
+    const predicate = input.spatialRel ?? "intersects";
+    const isPortableEnvelope = operand.geometryType === "esriGeometryEnvelope" && (predicate === "intersects" || predicate === "bbox-intersects");
+    if (isPortableEnvelope) {
+        return {
+            spatialFilter: {
+                geometry: operand.geometry,
+                geometryType: operand.geometryType,
+                spatialRel: predicate === "intersects" ? "esriSpatialRelIntersects" : "esriSpatialRelEnvelopeIntersects",
+            },
+        };
+    }
+    return { filterNode: { kind: "spatial", operator: predicate, geometry: operand } };
+}
+/**
+ * Lower the neutral tool input onto the SDK's canonical `Query`.
+ *
+ * The one protocol-specific compensation is `outFields`: a GeoServices
+ * `query` with no `outFields` returns OBJECTID only, whereas every other
+ * protocol returns all properties. Requesting `*` for the GeoServices family
+ * keeps "omit outFields ⇒ all fields" true across protocols rather than
+ * leaking an Esri default into the neutral contract.
+ */
+export function toQuery(input, options) {
+    const conjuncts = [];
+    if (input.filter !== undefined && input.filter !== null) {
+        conjuncts.push(toQueryFilter(filterSchema.parse(input.filter)));
+    }
+    const spatial = spatialConstraint(input);
+    if (spatial.filterNode)
+        conjuncts.push(spatial.filterNode);
+    const query = {};
+    const filter = andFilters(conjuncts);
+    if (filter)
+        query.filter = filter;
+    if (spatial.spatialFilter)
+        query.spatialFilter = spatial.spatialFilter;
+    if (input.where !== undefined && input.where.trim().length > 0)
+        query.where = input.where;
+    if (input.temporal)
+        query.temporalFilter = toTemporalFilter(input.temporal);
+    const outFields = input.outFields && input.outFields.length > 0
+        ? input.outFields
+        : isGeoServicesProtocol(options.protocol)
+            ? ["*"]
+            : undefined;
+    if (outFields)
+        query.outFields = outFields;
+    const orderBy = parseOrderBy(input.orderBy);
+    if (orderBy)
+        query.orderBy = orderBy;
+    if (options.paginate !== false) {
+        const pagination = { limit: clampLimit(input.limit) };
+        if (input.offset !== undefined)
+            pagination.offset = input.offset;
+        query.pagination = pagination;
+    }
+    else if (input.offset !== undefined || input.limit !== undefined) {
+        const pagination = {};
+        if (input.limit !== undefined)
+            pagination.limit = clampLimit(input.limit);
+        if (input.offset !== undefined)
+            pagination.offset = input.offset;
+        query.pagination = pagination;
+    }
+    if (input.returnGeometry !== undefined)
+        query.returnGeometry = input.returnGeometry;
+    if (input.outSr !== undefined)
+        query.outSr = input.outSr;
+    return query;
+}

package/dist/src/neutral/result.d.ts

@@ -0,0 +1,33 @@
+import type { DegradedReason, Result } from "@honua/sdk-js/contract";
+/**
+ * PROTOCOL-NEUTRAL result projection (#1005).
+ *
+ * A `Result` carries whatever geometry encoding its protocol produced —
+ * Esri-JSON from GeoServices, GeoJSON from OGC API Features / STAC. Returning
+ * that raw makes the tool output protocol-dependent, so the neutral contract
+ * normalizes to GeoJSON and says which encoding it used.
+ *
+ * `Result.degraded` is surfaced verbatim: when a protocol served a request a
+ * different way than asked (client-side aggregation on OGC, for example), the
+ * answer says so instead of quietly presenting a weaker number as authoritative.
+ */
+export type GeometryFormat = "geojson" | "esri-json";
+/** Re-encode one feature geometry into the requested format. */
+export declare function projectGeometry(geometry: Record<string, unknown> | null | undefined, format: GeometryFormat): Record<string, unknown> | null;
+/** Normalize `Result.degraded` for tool output; `undefined` when nothing degraded. */
+export declare function projectDegraded(degraded: readonly DegradedReason[] | undefined): {
+    capability: import("@honua/sdk-js/contract").Capability;
+    reason: string;
+    protocol: import("@honua/sdk-js/contract").Protocol | null;
+    sourceId: string | null;
+}[] | undefined;
+export interface ProjectFeaturesOptions {
+    readonly returnGeometry: boolean;
+    readonly geometryFormat: GeometryFormat;
+}
+/** Project canonical features onto the tool's neutral feature shape. */
+export declare function projectFeatures(result: Result, options: ProjectFeaturesOptions): {
+    geometry?: Record<string, unknown> | undefined;
+    attributes: Record<string, unknown>;
+}[];
+//# sourceMappingURL=result.d.ts.map

package/dist/src/neutral/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../../src/neutral/result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAGrE;;;;;;;;;;;GAWG;AAEH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,WAAW,CAAC;AAMrD,gEAAgE;AAChE,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EACpD,MAAM,EAAE,cAAc,GACrB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAMhC;AAED,sFAAsF;AACtF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,GAAG,SAAS;;;;;gBAQ9E;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;CACzC;AAED,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB;;;IAU9E"}

package/dist/src/neutral/result.js

@@ -0,0 +1,38 @@
+import { esriToGeoJson } from "@honua/sdk-js/geometry";
+function looksGeoJson(geometry) {
+    return typeof geometry.type === "string" && "coordinates" in geometry;
+}
+/** Re-encode one feature geometry into the requested format. */
+export function projectGeometry(geometry, format) {
+    if (!geometry)
+        return null;
+    if (format === "esri-json")
+        return geometry;
+    if (looksGeoJson(geometry))
+        return geometry;
+    const converted = esriToGeoJson(geometry);
+    return converted ? converted : null;
+}
+/** Normalize `Result.degraded` for tool output; `undefined` when nothing degraded. */
+export function projectDegraded(degraded) {
+    if (!degraded || degraded.length === 0)
+        return undefined;
+    return degraded.map((reason) => ({
+        capability: reason.capability,
+        reason: reason.reason,
+        protocol: reason.protocol ?? null,
+        sourceId: reason.sourceId ?? null,
+    }));
+}
+/** Project canonical features onto the tool's neutral feature shape. */
+export function projectFeatures(result, options) {
+    return result.features.map((feature) => {
+        const geometry = options.returnGeometry
+            ? projectGeometry(feature.geometry, options.geometryFormat)
+            : null;
+        return {
+            attributes: feature.attributes,
+            ...(geometry ? { geometry } : {}),
+        };
+    });
+}

package/dist/src/neutral/source-ref.d.ts

@@ -0,0 +1,126 @@
+import type { HonuaClient } from "@honua/sdk-js";
+import type { CapabilityAwareSource, SourceDescriptor, SourceLocator } from "@honua/sdk-js/contract";
+import { z } from "zod";
+/**
+ * PROTOCOL-NEUTRAL source addressing for the MCP tool contract (issue #1005).
+ *
+ * The tool surface used to address data the way GeoServices does — a required
+ * `serviceId` string plus a required numeric `layerId`. That vocabulary is
+ * meaningless on OGC API Features, STAC, WFS, and OData, so a "vendor-neutral"
+ * server whose only addressing mode is Esri-shaped concedes the claim on
+ * inspection.
+ *
+ * A source is now addressed the way the SDK addresses one: a
+ * `SourceDescriptor` (protocol + locator) resolved into a canonical
+ * `Source` through `createDataset`. Over the wire that descriptor is carried as
+ * one compact string:
+ *
+ * ```text
+ * <protocol>:<address>
+ * ```
+ *
+ * | protocol                        | address form          | example                                |
+ * | ------------------------------- | --------------------- | -------------------------------------- |
+ * | `geoservices-feature-service`   | `<serviceId>/<layer>` | `geoservices-feature-service:Parks/0`  |
+ * | `geoservices-map-service`       | `<serviceId>/<layer>` | `geoservices-map-service:Basemap/2`    |
+ * | `ogc-features`                  | `<collectionId>`      | `ogc-features:hotels`                  |
+ * | `ogc-records`                   | `<collectionId>`      | `ogc-records:catalog`                  |
+ * | `stac`                          | `<collectionId>`      | `stac:sentinel-2-l2a`                  |
+ * | `wfs`                           | `<typeName>`          | `wfs:topp:states`                      |
+ * | `odata`                         | `<entitySet>`         | `odata:People`                         |
+ *
+ * `honua_list_sources` emits exactly these strings, so the normal agent flow is
+ * discover-then-address with no parsing on the client side. The reference is
+ * deliberately fail-closed: an unrecognized protocol token is refused with the
+ * accepted forms rather than guessed at, because guessing "which protocol did
+ * they mean" is how a neutral surface silently becomes a single-vendor one.
+ *
+ * The legacy `serviceId` + `layerId` pair is still accepted (see
+ * {@link legacyGeoServicesRef}) but is deprecated and is no longer *required* by
+ * any schema.
+ */
+/** Protocols reachable through a `<protocol>:<address>` source reference. */
+export declare const SOURCE_REF_PROTOCOLS: readonly ["geoservices-feature-service", "geoservices-map-service", "ogc-features", "ogc-records", "stac", "wfs", "odata"];
+export type SourceRefProtocol = (typeof SOURCE_REF_PROTOCOLS)[number];
+/** Endpoint layouts an OGC API / STAC source may be published under. */
+export declare const SOURCE_LAYOUTS: readonly ["honua-facade", "ogc-api", "auto", "stac-api", "stac-static"];
+export type SourceLayout = (typeof SOURCE_LAYOUTS)[number];
+/** A parsed, validated protocol-neutral source reference. */
+export interface ParsedSourceRef {
+    /** Canonical `<protocol>:<address>` form (aliases normalized). */
+    readonly ref: string;
+    readonly protocol: SourceRefProtocol;
+    readonly address: string;
+    readonly layout?: SourceLayout;
+}
+export declare class SourceRefError extends Error {
+    readonly code = "INVALID_SOURCE_REFERENCE";
+    constructor(message: string);
+}
+/**
+ * Parse a `<protocol>:<address>` source reference. Fails closed: an omitted or
+ * unrecognized protocol token is refused with the accepted forms instead of
+ * being inferred, so a mistyped reference can never silently resolve against
+ * the wrong protocol.
+ */
+export declare function parseSourceRef(raw: string, layout?: SourceLayout): ParsedSourceRef;
+/** Build the canonical reference for the deprecated GeoServices `serviceId`/`layerId` pair. */
+export declare function legacyGeoServicesRef(serviceId: string, layerId: number): string;
+/** Project a parsed reference onto the SDK's protocol-neutral `SourceLocator`. */
+export declare function toSourceLocator(ref: ParsedSourceRef, baseUrl: string): SourceLocator;
+/** Build the `SourceDescriptor` a reference denotes, without contacting the endpoint. */
+export declare function toSourceDescriptor(ref: ParsedSourceRef, baseUrl: string): SourceDescriptor;
+/** A resolved source plus the neutral identity it was addressed by. */
+export interface ResolvedSource {
+    readonly ref: ParsedSourceRef;
+    readonly descriptor: SourceDescriptor;
+    readonly source: CapabilityAwareSource;
+    /** True when the caller used the deprecated `serviceId`/`layerId` pair. */
+    readonly legacyAddressing: boolean;
+}
+/**
+ * Zod fields every source-addressed tool mixes into its input schema.
+ *
+ * `source` is the protocol-neutral reference; `serviceId`/`layerId` remain as
+ * OPTIONAL, deprecated compatibility inputs so existing MCP clients keep
+ * working. No Esri-only field is required by any tool schema.
+ */
+export declare const sourceRefFields: {
+    readonly source: z.ZodOptional<z.ZodString>;
+    readonly layout: z.ZodOptional<z.ZodEnum<["honua-facade", "ogc-api", "auto", "stac-api", "stac-static"]>>;
+    readonly serviceId: z.ZodOptional<z.ZodString>;
+    readonly layerId: z.ZodOptional<z.ZodNumber>;
+};
+export type SourceRefInput = {
+    source?: string | undefined;
+    layout?: SourceLayout | undefined;
+    serviceId?: string | undefined;
+    layerId?: number | undefined;
+};
+/** Resolve the neutral reference an input addresses (without building a `Source`). */
+export declare function resolveSourceRef(input: SourceRefInput): {
+    ref: ParsedSourceRef;
+    legacyAddressing: boolean;
+};
+/**
+ * Resolve an input onto a canonical `Source`.
+ *
+ * The dataset runs under the `degraded` capability policy so a protocol that
+ * cannot serve a request first-party (OGC API Features has no server-side
+ * aggregation, for example) answers with an explicit `Result.degraded` reason
+ * instead of failing outright. Capabilities the protocol cannot serve at all
+ * still throw `HonuaCapabilityNotSupportedError`, which the tool layer turns
+ * into a structured tool error — never a silent empty result.
+ */
+export declare function resolveSource(client: HonuaClient, input: SourceRefInput): ResolvedSource;
+/** True when a resolved source speaks a GeoServices (Esri) protocol. */
+export declare function isGeoServicesProtocol(protocol: string): boolean;
+/**
+ * Resolve the OGC API Features endpoint layout a metadata call must use.
+ *
+ * `honua-facade` (the default) needs no resolution; a third-party OGC API root
+ * is discovered from its landing page once and cached on the client. STAC
+ * layouts are not OGC API Features layouts and resolve to `undefined`.
+ */
+export declare function ogcLayoutFor(client: HonuaClient, layout: SourceLayout | undefined): Promise<import("../../../dist/src/core/types.js").OgcEndpointLayout> | Promise<undefined>;
+//# sourceMappingURL=source-ref.d.ts.map

package/dist/src/neutral/source-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-ref.d.ts","sourceRoot":"","sources":["../../../src/neutral/source-ref.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,qBAAqB,EAAY,gBAAgB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAE/G,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,6EAA6E;AAC7E,eAAO,MAAM,oBAAoB,4HAQvB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAetE,wEAAwE;AACxE,eAAO,MAAM,cAAc,yEAA0E,CAAC;AAEtG,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;CAChC;AAED,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,8BAA8B;gBAE/B,OAAO,EAAE,MAAM;CAI5B;AAwBD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,eAAe,CA0BlF;AAED,+FAA+F;AAC/F,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE/E;AAiBD,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,GAAG,aAAa,CAiBpF;AAED,yFAAyF;AACzF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAO1F;AAED,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,2EAA2E;IAC3E,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACpC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,eAAe;;;;;CAyBlB,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,MAAM,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B,CAAC;AAEF,sFAAsF;AACtF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG;IAAE,GAAG,EAAE,eAAe,CAAC;IAAC,gBAAgB,EAAE,OAAO,CAAA;CAAE,CAuB3G;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,cAAc,GAAG,cAAc,CAiCxF;AAED,wEAAwE;AACxE,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,GAAG,SAAS,6FAKjF"}