@honua/mcp-server 0.1.2-beta.0 → 0.1.8-beta.0

package/dist/src/neutral/filter.js

@@ -0,0 +1,271 @@
+import { geoJsonToEsri } from "@honua/sdk-js/geometry";
+import { z } from "zod";
+import { GEOMETRY_TYPES, resolveGeometryType } from "../helpers.js";
+/**
+ * PROTOCOL-NEUTRAL filter + geometry vocabulary for the MCP tool contract (#1005).
+ *
+ * The SDK's `Query.filter` is a typed semantic filter that compiles to
+ * GeoServices SQL-92, CQL2 (OGC API Features / STAC), FES 2.0 (WFS), OData
+ * `$filter`, and DuckDB SQL — and refuses, naming the construct and the
+ * protocol, when a target cannot express a construct exactly. Exposing it on
+ * the tool surface is what lets an agent write ONE filter and have it mean the
+ * same thing on every backend, instead of hand-writing Esri SQL.
+ *
+ * The wire shape here is a flattened projection of that AST: one `op`
+ * discriminator per node instead of the SDK's `kind` + `operator` pair, because
+ * a flat discriminated union is markedly easier for a model to emit correctly.
+ * {@link toQueryFilter} lowers it onto the canonical expression losslessly.
+ *
+ * Geometry is canonical **GeoJSON** (RFC 7946). Esri-JSON geometry is still
+ * accepted for compatibility with existing clients and is converted on the way
+ * in; nothing on the surface requires it.
+ */
+const scalarSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+/** Protocol-neutral spatial predicates (`QueryFilterSpatialPredicate`). */
+export const SPATIAL_PREDICATES = [
+    "intersects",
+    "contains",
+    "within",
+    "crosses",
+    "touches",
+    "overlaps",
+    "bbox-intersects",
+];
+const TEMPORAL_PREDICATES = ["before", "after", "during", "time-intersects"];
+/** GeoJSON geometry accepted anywhere a spatial constraint is expressed. */
+export const geoJsonGeometrySchema = z
+    .object({
+    type: z.enum(["Point", "MultiPoint", "LineString", "MultiLineString", "Polygon", "MultiPolygon"]),
+    coordinates: z.array(z.unknown()),
+})
+    .passthrough();
+/**
+ * A geometry operand: GeoJSON (canonical) or Esri-JSON (accepted for
+ * compatibility). Kept as a loose record so an Esri envelope / rings payload
+ * from an existing client still validates.
+ */
+export const geometrySchema = z.record(z.unknown());
+export const bboxSchema = z
+    .array(z.number())
+    .length(4)
+    .describe("Bounding box [minX, minY, maxX, maxY]. Interpreted in the source CRS (WGS84 unless bboxSrid says otherwise).");
+/**
+ * Recursive zod schema for {@link FilterNode}. `z.lazy` keeps `and`/`or`/`not`
+ * genuinely recursive; zod-to-json-schema emits it as a `$ref`, which stays
+ * well-formed JSON Schema for MCP clients and for the certification harness.
+ */
+export const filterSchema = z.lazy(() => z.union([
+    z.object({
+        op: z.enum(["and", "or"]),
+        args: z.array(filterSchema).min(1),
+    }),
+    z.object({ op: z.literal("not"), arg: filterSchema }),
+    z.object({
+        op: z.enum(["eq", "ne", "lt", "lte", "gt", "gte"]),
+        field: z.string().min(1),
+        value: scalarSchema,
+    }),
+    z.object({ op: z.literal("in"), field: z.string().min(1), values: z.array(scalarSchema).min(1) }),
+    z.object({
+        op: z.literal("between"),
+        field: z.string().min(1),
+        lower: scalarSchema,
+        upper: scalarSchema,
+    }),
+    z.object({ op: z.enum(["is-null", "is-not-null"]), field: z.string().min(1) }),
+    z.object({
+        op: z.literal("like"),
+        field: z.string().min(1),
+        pattern: z.string(),
+        caseSensitive: z.boolean().optional(),
+    }),
+    z.object({
+        op: z.enum(SPATIAL_PREDICATES),
+        geometry: geometrySchema.optional(),
+        bbox: z.array(z.number()).length(4).optional(),
+        field: z.string().optional(),
+        geometryType: z.enum(GEOMETRY_TYPES).optional(),
+    }),
+    z.object({
+        op: z.enum(TEMPORAL_PREDICATES),
+        field: z.string().min(1),
+        // An interval is a 2-element array rather than a JSON Schema tuple: the
+        // draft-07 tuple form (`items: [...]`) is invalid under 2020-12, and the
+        // certification harness validates advertised schemas under both dialects.
+        value: z.union([z.string(), z.array(z.string()).length(2)]),
+    }),
+]));
+export class FilterInputError extends Error {
+    code = "INVALID_FILTER";
+    constructor(message) {
+        super(message);
+        this.name = "FilterInputError";
+    }
+}
+function isGeoJsonGeometry(value) {
+    return typeof value.type === "string" && Array.isArray(value.coordinates);
+}
+/** Build an Esri envelope from a `[minX, minY, maxX, maxY]` bbox. */
+export function bboxToOperand(bbox, srid) {
+    const [xmin, ymin, xmax, ymax] = bbox;
+    const geometry = { xmin, ymin, xmax, ymax };
+    if (srid !== undefined) {
+        geometry.spatialReference = { wkid: srid };
+    }
+    return { geometry, geometryType: "esriGeometryEnvelope" };
+}
+/**
+ * Normalize a geometry input onto the canonical geometry operand.
+ *
+ * GeoJSON is the documented input; Esri-JSON is accepted so existing clients
+ * keep working. The canonical operand is Esri-shaped inside the SDK — that is
+ * an SDK implementation detail, not part of this tool contract.
+ */
+export function toGeometryOperand(geometry, esriGeometryType, srid) {
+    if (isGeoJsonGeometry(geometry)) {
+        const converted = geoJsonToEsri(geometry, srid !== undefined ? { wkid: srid } : undefined);
+        if (!converted) {
+            throw new FilterInputError(`GeoJSON geometry of type "${String(geometry.type)}" could not be converted to a query geometry.`);
+        }
+        const asRecord = converted;
+        const geometryType = resolveGeometryType(asRecord, undefined);
+        if (!geometryType) {
+            throw new FilterInputError("Converted geometry has no recognizable geometry type.");
+        }
+        return { geometry: asRecord, geometryType };
+    }
+    const geometryType = resolveGeometryType(geometry, esriGeometryType);
+    if (!geometryType) {
+        throw new FilterInputError('geometry is neither GeoJSON (an object with "type" and "coordinates") nor a recognizable Esri-JSON geometry. Pass GeoJSON, a bbox, or an explicit geometryType.');
+    }
+    return { geometry, geometryType };
+}
+function spatialOperand(node) {
+    if (node.geometry && node.bbox) {
+        throw new FilterInputError(`filter node "${node.op}" carries both geometry and bbox; pass exactly one.`);
+    }
+    if (node.bbox) {
+        return bboxToOperand(node.bbox);
+    }
+    if (node.geometry) {
+        return toGeometryOperand(node.geometry, node.geometryType);
+    }
+    throw new FilterInputError(`filter node "${node.op}" requires either geometry (GeoJSON) or bbox.`);
+}
+function isSpatialOp(op) {
+    return SPATIAL_PREDICATES.includes(op);
+}
+function isTemporalOp(op) {
+    return TEMPORAL_PREDICATES.includes(op);
+}
+/** Lower the wire filter DSL onto the SDK's canonical typed filter expression. */
+export function toQueryFilter(node) {
+    switch (node.op) {
+        case "and":
+        case "or":
+            return { kind: "boolean", operator: node.op, args: node.args.map(toQueryFilter) };
+        case "not":
+            return { kind: "not", arg: toQueryFilter(node.arg) };
+        case "eq":
+        case "ne":
+        case "lt":
+        case "lte":
+        case "gt":
+        case "gte":
+            return {
+                kind: "comparison",
+                operator: node.op,
+                left: { kind: "property", name: node.field },
+                right: { kind: "literal", value: node.value },
+            };
+        case "in":
+            return {
+                kind: "list",
+                operator: "in",
+                operand: { kind: "property", name: node.field },
+                values: node.values.map((value) => ({ kind: "literal", value })),
+            };
+        case "between":
+            return {
+                kind: "range",
+                operator: "between",
+                operand: { kind: "property", name: node.field },
+                lower: { kind: "literal", value: node.lower },
+                upper: { kind: "literal", value: node.upper },
+            };
+        case "is-null":
+        case "is-not-null":
+            return { kind: "null", operator: node.op, operand: { kind: "property", name: node.field } };
+        case "like":
+            return {
+                kind: "pattern",
+                operator: "like",
+                operand: { kind: "property", name: node.field },
+                pattern: node.pattern,
+                ...(node.caseSensitive === undefined ? {} : { caseSensitive: node.caseSensitive }),
+            };
+        default:
+            break;
+    }
+    if (isSpatialOp(node.op)) {
+        const spatial = node;
+        return {
+            kind: "spatial",
+            operator: spatial.op,
+            geometry: spatialOperand(spatial),
+            ...(spatial.field ? { property: spatial.field } : {}),
+        };
+    }
+    if (isTemporalOp(node.op)) {
+        const temporal = node;
+        const value = temporal.value;
+        return {
+            kind: "temporal",
+            operator: temporal.op,
+            operand: { kind: "property", name: temporal.field },
+            value: typeof value === "string"
+                ? { kind: "temporal-literal", valueType: "instant", value }
+                : { kind: "temporal-literal", valueType: "interval", value: [value[0], value[1]] },
+        };
+    }
+    throw new FilterInputError(`unknown filter operator "${String(node.op)}".`);
+}
+/** Conjoin filter expressions; `undefined` when nothing was supplied. */
+export function andFilters(parts) {
+    if (parts.length === 0)
+        return undefined;
+    if (parts.length === 1)
+        return parts[0];
+    return { kind: "boolean", operator: "and", args: [...parts] };
+}
+/** Canonical time constraint accepted on the tool surface. */
+export const temporalSchema = z
+    .object({
+    instant: z.string().optional().describe("RFC 3339 instant, e.g. 2026-05-01T00:00:00Z."),
+    start: z.string().nullable().optional().describe("Interval start (null = open ended)."),
+    end: z.string().nullable().optional().describe("Interval end (null = open ended)."),
+    field: z
+        .string()
+        .optional()
+        .describe("Time column to constrain. Omit to target the source's own time dimension (GeoServices time=, OGC/STAC datetime=); OData, WFS, and GeoParquet require an explicit field."),
+})
+    .describe("Protocol-neutral time constraint: either `instant`, or `start`/`end` for an interval.");
+/** Lower the wire temporal input onto `Query.temporalFilter`. */
+export function toTemporalFilter(input) {
+    const field = input.field ? { field: input.field } : {};
+    if (input.instant !== undefined) {
+        if (input.start !== undefined || input.end !== undefined) {
+            throw new FilterInputError("temporal accepts either `instant` or `start`/`end`, not both.");
+        }
+        return { kind: "instant", instant: input.instant, ...field };
+    }
+    if (input.start === undefined && input.end === undefined) {
+        throw new FilterInputError("temporal requires `instant`, or at least one of `start` / `end`.");
+    }
+    return {
+        kind: "interval",
+        start: input.start ?? null,
+        end: input.end ?? null,
+        ...field,
+    };
+}

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 } : {}),
+        };
+    });
+}