@honua/mcp-server 0.0.9-alpha.0 → 0.0.20-alpha.0

package/dist/src/certification/contracts.js

@@ -0,0 +1,174 @@
+import { McpError } from "@modelcontextprotocol/sdk/types.js";
+import { validateAgainstSchema } from "./json-schema.js";
+import { loadSchemaFile } from "./schema-index.js";
+/**
+ * Pure, deterministic contract-check analyzers for MCP certification.
+ *
+ * These operate on values already obtained from the certified surface (tool
+ * results, thrown errors, paginated list responses) so they are unit-testable
+ * without any transport. The certifier does the I/O; these judge the shape.
+ *
+ * Contracts enforced (§P0.2):
+ *   - output-schema : a tool's structuredContent validates against its outputSchema.
+ *   - error-shape   : invalid arguments yield an `isError` tool result carrying a
+ *                     structured, actionable code (validated against the vendored
+ *                     geoprocessing-error schema), never a protocol error.
+ *   - auth          : unauthenticated tools/call and resources/read surface a
+ *                     structured `unauthenticated` / `permission_denied` signal.
+ *   - pagination    : list `nextCursor` is honored and terminates.
+ */
+/** Machine codes that satisfy the unauthenticated / permission-denied contract. */
+export const AUTH_ERROR_CODES = ["unauthenticated", "permission_denied"];
+/** geoprocessing-error `kind` values that denote an authorization failure. */
+export const AUTH_ERROR_KINDS = ["AuthorizationDenied", "Unauthenticated", "PermissionDenied"];
+let cachedErrorSchema;
+function geoprocessingErrorSchema() {
+    if (!cachedErrorSchema) {
+        cachedErrorSchema = loadSchemaFile("common/geoprocessing-error.schema.json");
+    }
+    return cachedErrorSchema;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+/**
+ * Normalize a structured error envelope out of any of the places a surface may
+ * carry it: a tool result's `structuredContent`, an `McpError`'s `data`, or a
+ * bare geoprocessing-error object. Returns undefined when no structure is found.
+ */
+export function extractStructuredError(source) {
+    if (source instanceof McpError) {
+        const fromData = extractStructuredError(source.data);
+        if (fromData) {
+            return fromData;
+        }
+        // A raw code may live on the error's message-less data; nothing structured.
+        return undefined;
+    }
+    if (!isRecord(source)) {
+        return undefined;
+    }
+    // Tool result → dig into structuredContent first.
+    if (isRecord(source.structuredContent)) {
+        const nested = extractStructuredError(source.structuredContent);
+        if (nested) {
+            return nested;
+        }
+    }
+    const code = typeof source.code === "string" ? source.code : undefined;
+    // Envelope with a nested geoprocessing-error under `error`.
+    if (isRecord(source.error)) {
+        return { code, error: source.error };
+    }
+    // The object may itself be a geoprocessing-error (has `kind` + `message`).
+    if (typeof source.kind === "string" && typeof source.message === "string") {
+        return { code, error: source };
+    }
+    if (code) {
+        return { code };
+    }
+    return undefined;
+}
+/** Validate a value against the vendored geoprocessing-error schema. */
+export function validateGeoprocessingError(error) {
+    const result = validateAgainstSchema(geoprocessingErrorSchema(), error);
+    return { ok: result.valid, errors: result.errors };
+}
+/**
+ * error-shape contract: an invalid-argument tool call must return an `isError`
+ * result whose structuredContent carries an actionable code and a
+ * geoprocessing-error-shaped `ValidationFailed` envelope.
+ */
+export function checkInvalidArgsContract(result) {
+    const errors = [];
+    if (result.isError !== true) {
+        errors.push("expected isError=true for an invalid-argument call (got a protocol error or a success)");
+    }
+    const envelope = extractStructuredError(result);
+    if (!envelope) {
+        errors.push("no structured error envelope found on the tool result");
+        return { ok: false, errors };
+    }
+    if (!envelope.code || envelope.code.trim().length === 0) {
+        errors.push("structured error is missing a machine-actionable `code`");
+    }
+    if (envelope.error === undefined) {
+        errors.push("structured error is missing a geoprocessing-error envelope");
+    }
+    else {
+        const validation = validateGeoprocessingError(envelope.error);
+        if (!validation.ok) {
+            errors.push(...validation.errors.map((e) => `geoprocessing-error: ${e}`));
+        }
+        const kind = isRecord(envelope.error) ? envelope.error.kind : undefined;
+        if (kind !== "ValidationFailed") {
+            errors.push(`expected geoprocessing-error kind "ValidationFailed", got "${String(kind)}"`);
+        }
+        const violations = isRecord(envelope.error) ? envelope.error.violations : undefined;
+        if (!Array.isArray(violations) || violations.length === 0) {
+            errors.push("expected at least one structured validation `violation`");
+        }
+    }
+    return { ok: errors.length === 0, errors };
+}
+/**
+ * auth contract: an unauthenticated call must surface a structured
+ * `unauthenticated` / `permission_denied` signal — either as a code on the
+ * envelope or as an AuthorizationDenied geoprocessing-error kind.
+ */
+export function checkAuthContract(source) {
+    const envelope = extractStructuredError(source);
+    if (!envelope) {
+        return { ok: false, errors: ["no structured error found for the unauthenticated request"] };
+    }
+    const code = envelope.code;
+    const kind = isRecord(envelope.error) ? envelope.error.kind : undefined;
+    const codeOk = typeof code === "string" && AUTH_ERROR_CODES.includes(code);
+    const kindOk = typeof kind === "string" && AUTH_ERROR_KINDS.includes(kind);
+    if (codeOk || kindOk) {
+        return { ok: true, errors: [] };
+    }
+    return {
+        ok: false,
+        errors: [
+            `expected a structured auth signal (code in [${AUTH_ERROR_CODES.join(", ")}] or kind in [${AUTH_ERROR_KINDS.join(", ")}]), got code="${String(code)}" kind="${String(kind)}"`,
+        ],
+    };
+}
+/**
+ * pagination contract: following `nextCursor` yields additional distinct items,
+ * never repeats a cursor (terminates), and the final page has no cursor.
+ */
+export function checkPaginationContract(pages) {
+    const errors = [];
+    if (pages.length === 0) {
+        return { ok: false, errors: ["no list pages captured"] };
+    }
+    const seenCursors = new Set();
+    const seenKeys = new Set();
+    for (let i = 0; i < pages.length; i++) {
+        const page = pages[i];
+        for (const key of page.keys) {
+            seenKeys.add(key);
+        }
+        const isLast = i === pages.length - 1;
+        if (!isLast) {
+            if (!page.nextCursor) {
+                errors.push(`page ${i} is not the last page but advertised no nextCursor`);
+            }
+            else if (seenCursors.has(page.nextCursor)) {
+                errors.push(`nextCursor "${page.nextCursor}" repeated — pagination does not terminate`);
+            }
+            else {
+                seenCursors.add(page.nextCursor);
+            }
+        }
+        else if (page.nextCursor) {
+            errors.push(`final page still advertises nextCursor "${page.nextCursor}" — pagination did not terminate`);
+        }
+    }
+    if (pages.length > 1 && seenKeys.size <= pages[0].keys.length) {
+        errors.push("following nextCursor did not yield any additional distinct items");
+    }
+    return { ok: errors.length === 0, errors };
+}

package/dist/src/certification/fixture-client.d.ts

@@ -0,0 +1,4 @@
+import type { HonuaClient } from "@honua/sdk-js";
+/** Build an offline fixture client usable anywhere a `HonuaClient` is expected. */
+export declare function createFixtureClient(): HonuaClient;
+//# sourceMappingURL=fixture-client.d.ts.map

package/dist/src/certification/fixture-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixture-client.d.ts","sourceRoot":"","sources":["../../../src/certification/fixture-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EAKZ,MAAM,eAAe,CAAC;AAsDvB,mFAAmF;AACnF,wBAAgB,mBAAmB,IAAI,WAAW,CAkEjD"}

package/dist/src/certification/fixture-client.js

@@ -0,0 +1,113 @@
+/**
+ * Offline fixture `HonuaClient` for deterministic certification.
+ *
+ * This is the standalone (non-vitest) counterpart of `test/test-helpers.ts`:
+ * it returns canned, schema-shaped responses for every method the MCP tools and
+ * resources call, so the certifier can run `tools/call` round-trips with no live
+ * backend, no network access, and no model/API calls. CI instead points the
+ * certifier at a live honua-server via `createClientFromEnv`.
+ */
+const STYLES_LIST = {
+    styles: [
+        { id: "topographic", title: "Topographic", links: [] },
+        { id: "imagery", title: "Imagery", links: [] },
+    ],
+    default: "topographic",
+};
+const TOPOGRAPHIC_METADATA = {
+    id: "topographic",
+    title: "Topographic",
+    description: "Default topographic basemap style",
+    version: "3",
+    links: [{ rel: "preview", type: "image/png", href: "https://example.test/ogc/styles/topographic/preview" }],
+};
+const TOPOGRAPHIC_STYLESHEET = {
+    version: 8,
+    name: "Topographic",
+    layers: [{ id: "background", type: "background" }],
+};
+function jsonResponse(body, status = 200) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "Content-Type": "application/json" },
+    });
+}
+async function fixtureFetch(_method, path) {
+    if (path === "/ogc/styles") {
+        return jsonResponse(STYLES_LIST);
+    }
+    if (path === "/ogc/styles/topographic/metadata") {
+        return jsonResponse(TOPOGRAPHIC_METADATA);
+    }
+    if (path === "/ogc/styles/topographic") {
+        return jsonResponse(TOPOGRAPHIC_STYLESHEET);
+    }
+    return jsonResponse({ error: "not found" }, 404);
+}
+/** Build an offline fixture client usable anywhere a `HonuaClient` is expected. */
+export function createFixtureClient() {
+    const client = {
+        serverBaseUrl: "https://example.test",
+        async listServices() {
+            return {
+                services: [
+                    { name: "Parks", type: "FeatureServer" },
+                    { name: "Basemap", type: "MapServer" },
+                    { name: "Census", type: "FeatureServer" },
+                ],
+            };
+        },
+        async getFeatureServiceMetadata(_serviceId) {
+            return {
+                serviceDescription: "Test service",
+                layers: [
+                    { id: 0, name: "Layer 0" },
+                    { id: 1, name: "Layer 1" },
+                ],
+                spatialReference: { wkid: 4326 },
+            };
+        },
+        async getLayerMetadata(_serviceId, _layerId) {
+            return {
+                id: 0,
+                name: "Test Layer",
+                description: "A test layer",
+                geometryType: "esriGeometryPoint",
+                fields: [
+                    { name: "OBJECTID", type: "esriFieldTypeOID" },
+                    { name: "NAME", type: "esriFieldTypeString", alias: "Feature Name" },
+                    { name: "VALUE", type: "esriFieldTypeDouble" },
+                ],
+                extent: { xmin: -180, ymin: -90, xmax: 180, ymax: 90 },
+                spatialReference: { wkid: 4326 },
+                relationships: [{ id: 0, name: "rel_0", relatedTableId: 1 }],
+            };
+        },
+        async queryFeatures(request) {
+            const extraParams = request?.extraParams ?? {};
+            // count-only and extent-only projections mirror the GeoServices query
+            // surface the tools exercise (returnCountOnly / returnExtentOnly).
+            if (extraParams.returnCountOnly === true) {
+                return { count: 2 };
+            }
+            if (extraParams.returnExtentOnly === true) {
+                return {
+                    count: 2,
+                    extent: { xmin: -180, ymin: -90, xmax: 180, ymax: 90, spatialReference: { wkid: 4326 } },
+                };
+            }
+            return {
+                objectIdFieldName: "OBJECTID",
+                geometryType: "esriGeometryPoint",
+                spatialReference: { wkid: 4326 },
+                features: [
+                    { attributes: { OBJECTID: 1, NAME: "Park A", VALUE: 100 } },
+                    { attributes: { OBJECTID: 2, NAME: "Park B", VALUE: 200 } },
+                ],
+                exceededTransferLimit: false,
+            };
+        },
+        pipelineFetch: fixtureFetch,
+    };
+    return client;
+}

package/dist/src/certification/fixtures.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Deterministic round-trip fixture inputs for the honua `/mcp` operator surface.
+ *
+ * Certification calls `tools/call` on read-only operator tools to validate their
+ * structured output against the advertised outputSchema. Inputs are resolved
+ * from environment overrides so the same harness drives both the offline mock
+ * upstream and a live honua-server `/mcp` in remote mode, without ever calling a
+ * mutating tool (execute/cancel/publish/propose/create).
+ */
+export interface RoundTripEnv {
+    serviceId: string;
+    layerId: number;
+    address: string;
+    styleId: string | undefined;
+}
+/** Resolve round-trip identifiers from the environment, with safe fallbacks. */
+export declare function resolveRoundTripEnv(env?: NodeJS.ProcessEnv): RoundTripEnv;
+/**
+ * Build the read-only round-trip argument map keyed by advertised tool name.
+ * Tools without a fixture entry are still discovered, schema/conformance/output
+ * checked, but are not round-tripped (no call is made). Mutating tools are never
+ * listed here.
+ */
+export declare function buildRoundTripInputs(env: RoundTripEnv): Record<string, Record<string, unknown>>;
+/**
+ * A deliberately invalid argument set for the error-shape contract. Certification
+ * picks the first advertised tool that has an entry here and calls it with these
+ * args, expecting a structured `ValidationFailed` tool result (not a protocol
+ * error). `honua_query_features` requires `layerId`, so omitting it is invalid.
+ */
+export declare function buildInvalidArgsInputs(): Record<string, Record<string, unknown>>;
+//# sourceMappingURL=fixtures.d.ts.map

package/dist/src/certification/fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.d.ts","sourceRoot":"","sources":["../../../src/certification/fixtures.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED,gFAAgF;AAChF,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,YAAY,CAQtF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAyB/F;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAMhF"}

package/dist/src/certification/fixtures.js

@@ -0,0 +1,64 @@
+/**
+ * Deterministic round-trip fixture inputs for the honua `/mcp` operator surface.
+ *
+ * Certification calls `tools/call` on read-only operator tools to validate their
+ * structured output against the advertised outputSchema. Inputs are resolved
+ * from environment overrides so the same harness drives both the offline mock
+ * upstream and a live honua-server `/mcp` in remote mode, without ever calling a
+ * mutating tool (execute/cancel/publish/propose/create).
+ */
+/** Resolve round-trip identifiers from the environment, with safe fallbacks. */
+export function resolveRoundTripEnv(env = process.env) {
+    const serviceId = env.HONUA_MCP_SERVICE_ID ?? env.HONUA_SERVICE_ID ?? "svc-parks";
+    const layerRaw = env.HONUA_MCP_LAYER_ID ?? env.HONUA_LAYER_ID ?? "0";
+    const parsedLayer = Number.parseInt(layerRaw, 10);
+    const layerId = Number.isFinite(parsedLayer) && parsedLayer >= 0 ? parsedLayer : 0;
+    const address = env.HONUA_MCP_ADDRESS ?? "1600 Pennsylvania Ave NW, Washington DC";
+    const styleId = env.HONUA_MCP_STYLE_ID ?? env.HONUA_STYLE_ID;
+    return { serviceId, layerId, address, styleId };
+}
+/**
+ * Build the read-only round-trip argument map keyed by advertised tool name.
+ * Tools without a fixture entry are still discovered, schema/conformance/output
+ * checked, but are not round-tripped (no call is made). Mutating tools are never
+ * listed here.
+ */
+export function buildRoundTripInputs(env) {
+    const { serviceId, layerId, address } = env;
+    return {
+        honua_list_layers: {},
+        honua_list_capabilities: {},
+        honua_query_features: { serviceId, layerId, limit: 1 },
+        honua_render_map: { layers: [{ serviceId, layerId }], bbox: [-77.1, 38.8, -76.9, 39.0] },
+        honua_geocode_address: { address },
+        honua_solve_route: {
+            stops: [
+                { lon: -77.03, lat: 38.9 },
+                { lon: -76.61, lat: 39.29 },
+            ],
+        },
+        honua_plan_analysis: { intent: "Count parks within the district boundary" },
+        honua_ground_candidates: { goal: "Analyze park coverage" },
+        honua_clarify_intent: {
+            goal: "Analyze park coverage",
+            intentId: "int-001",
+            response: { answers: { q1: ["yes"] } },
+        },
+        honua_validate_plan: { plan: {} },
+        honua_dry_run_plan: { plan: { planId: "plan-001", steps: [{ stepId: "s1", kind: "QueryFeatures" }] } },
+        honua_resolve_entity: { text: "parks" },
+    };
+}
+/**
+ * A deliberately invalid argument set for the error-shape contract. Certification
+ * picks the first advertised tool that has an entry here and calls it with these
+ * args, expecting a structured `ValidationFailed` tool result (not a protocol
+ * error). `honua_query_features` requires `layerId`, so omitting it is invalid.
+ */
+export function buildInvalidArgsInputs() {
+    return {
+        honua_query_features: { serviceId: "svc-parks" },
+        honua_geocode_address: { maxResults: 3 },
+        honua_solve_route: { travelProfile: "driving" },
+    };
+}

package/dist/src/certification/json-schema.d.ts

@@ -0,0 +1,49 @@
+import type { ValidateFunction } from "ajv/dist/2020.js";
+import type { JsonSchema } from "./schema-index.js";
+export interface WellFormedResult {
+    wellFormed: boolean;
+    errors: string[];
+}
+/**
+ * Check that a value is a structurally well-formed JSON Schema by asking Ajv to
+ * compile it. A schema that compiles is usable as a validator; a schema Ajv
+ * refuses to compile is malformed.
+ */
+export declare function checkWellFormed(schema: unknown): WellFormedResult;
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/** Compile a schema into a reusable validator, or throw a descriptive error. */
+export declare function compileValidator(schema: JsonSchema): ValidateFunction;
+/** Validate a value against a JSON Schema and collect human-readable errors. */
+export declare function validateAgainstSchema(schema: JsonSchema, value: unknown): ValidationResult;
+export interface ConformanceResult {
+    conformant: boolean;
+    /** Required standard properties the advertised schema honors. */
+    matchedRequired: string[];
+    /** Conformance violations (missing or type-incompatible required properties). */
+    violations: string[];
+    /** Non-fatal observations (e.g. advertised extra properties, type widenings). */
+    notes: string[];
+}
+/**
+ * Deterministically compare an advertised tool inputSchema against a standard
+ * geospatial-mcp tool schema.
+ *
+ * Conformance contract (intentionally permissive to avoid false negatives — we
+ * fail only on demonstrable non-conformance, never on the absence of a tool):
+ *
+ *   1. Every property the standard marks `required` MUST be present in the
+ *      advertised schema's properties (a client that follows the standard will
+ *      send it, so the tool must accept it).
+ *   2. For each such required property, when both schemas declare a `type`, the
+ *      advertised type must be compatible (equal, or a superset, or `integer`
+ *      accepted where the standard says `number`).
+ *
+ * Extra advertised properties and looser-but-compatible types are recorded as
+ * notes, not violations: a richer reference shape is allowed to extend the
+ * bare standard.
+ */
+export declare function checkConformance(advertised: JsonSchema, standard: JsonSchema): ConformanceResult;
+//# sourceMappingURL=json-schema.d.ts.map

package/dist/src/certification/json-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.d.ts","sourceRoot":"","sources":["../../../src/certification/json-schema.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAA2C,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAElG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAwBpD,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,gBAAgB,CAcjE;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AASD,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,gBAAgB,CAGrE;AAED,gFAAgF;AAChF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAQ1F;AAmCD,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,OAAO,CAAC;IACpB,iEAAiE;IACjE,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,iFAAiF;IACjF,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,iFAAiF;IACjF,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,GAAG,iBAAiB,CAwDhG"}

package/dist/src/certification/json-schema.js

@@ -0,0 +1,164 @@
+import { Ajv2020 } from "ajv/dist/2020.js";
+import draft07MetaSchema from "ajv/dist/refs/json-schema-draft-07.json" with { type: "json" };
+/**
+ * Deterministic JSON Schema utilities for certification.
+ *
+ * Two dialects appear in practice:
+ *   - The vendored geospatial-mcp standard schemas declare draft 2020-12.
+ *   - MCP tool `inputSchema`s emitted via zod-to-json-schema declare draft-07.
+ *
+ * A single Ajv 2020-12 core handles both: we register the draft-07 meta-schema
+ * so a schema that declares `$schema: ".../draft-07/schema#"` resolves instead
+ * of erroring with "no schema with key/ref". All work is in-process: no network
+ * access, no model calls.
+ *
+ * `strict: false` tolerates non-standard annotation keywords (e.g.
+ * `x-honua-reference-shape`); `validateFormats: false` keeps well-formedness
+ * purely structural and offline.
+ */
+function createAjv() {
+    const ajv = new Ajv2020({ strict: false, allErrors: true, validateFormats: false });
+    ajv.addMetaSchema(draft07MetaSchema);
+    return ajv;
+}
+/**
+ * Check that a value is a structurally well-formed JSON Schema by asking Ajv to
+ * compile it. A schema that compiles is usable as a validator; a schema Ajv
+ * refuses to compile is malformed.
+ */
+export function checkWellFormed(schema) {
+    if (schema === undefined || schema === null) {
+        return { wellFormed: false, errors: ["schema is missing (null/undefined)"] };
+    }
+    if (typeof schema !== "object") {
+        return { wellFormed: false, errors: [`schema must be an object, got ${typeof schema}`] };
+    }
+    try {
+        const ajv = createAjv();
+        ajv.compile(schema);
+        return { wellFormed: true, errors: [] };
+    }
+    catch (err) {
+        return { wellFormed: false, errors: [err instanceof Error ? err.message : String(err)] };
+    }
+}
+function formatErrors(errors) {
+    if (!errors) {
+        return [];
+    }
+    return errors.map((e) => `${e.instancePath || "(root)"} ${e.message ?? "is invalid"}`.trim());
+}
+/** Compile a schema into a reusable validator, or throw a descriptive error. */
+export function compileValidator(schema) {
+    const ajv = createAjv();
+    return ajv.compile(schema);
+}
+/** Validate a value against a JSON Schema and collect human-readable errors. */
+export function validateAgainstSchema(schema, value) {
+    try {
+        const validate = compileValidator(schema);
+        const valid = validate(value);
+        return { valid, errors: valid ? [] : formatErrors(validate.errors) };
+    }
+    catch (err) {
+        return { valid: false, errors: [err instanceof Error ? err.message : String(err)] };
+    }
+}
+/**
+ * Extract the top-level property names a JSON Schema accepts, when discoverable
+ * from a plain `type: object` shape. Returns undefined when the property set is
+ * not statically enumerable (e.g. additionalProperties / combinators only).
+ */
+function objectPropertyNames(schema) {
+    const props = schema.properties;
+    if (props && typeof props === "object") {
+        return new Set(Object.keys(props));
+    }
+    return undefined;
+}
+function requiredPropertyNames(schema) {
+    const required = schema.required;
+    return Array.isArray(required) ? required.filter((r) => typeof r === "string") : [];
+}
+/** Normalize a JSON Schema `type` (string or array) into a set. */
+function schemaTypes(schema) {
+    if (!schema) {
+        return new Set();
+    }
+    const t = schema.type;
+    if (typeof t === "string") {
+        return new Set([t]);
+    }
+    if (Array.isArray(t)) {
+        return new Set(t.filter((x) => typeof x === "string"));
+    }
+    return new Set();
+}
+/**
+ * Deterministically compare an advertised tool inputSchema against a standard
+ * geospatial-mcp tool schema.
+ *
+ * Conformance contract (intentionally permissive to avoid false negatives — we
+ * fail only on demonstrable non-conformance, never on the absence of a tool):
+ *
+ *   1. Every property the standard marks `required` MUST be present in the
+ *      advertised schema's properties (a client that follows the standard will
+ *      send it, so the tool must accept it).
+ *   2. For each such required property, when both schemas declare a `type`, the
+ *      advertised type must be compatible (equal, or a superset, or `integer`
+ *      accepted where the standard says `number`).
+ *
+ * Extra advertised properties and looser-but-compatible types are recorded as
+ * notes, not violations: a richer reference shape is allowed to extend the
+ * bare standard.
+ */
+export function checkConformance(advertised, standard) {
+    const violations = [];
+    const notes = [];
+    const matchedRequired = [];
+    const standardRequired = requiredPropertyNames(standard);
+    const standardProps = (standard.properties ?? {});
+    const advertisedProps = (advertised.properties ?? {});
+    const advertisedNames = objectPropertyNames(advertised);
+    for (const name of standardRequired) {
+        const present = advertisedNames ? advertisedNames.has(name) : name in advertisedProps;
+        if (!present) {
+            violations.push(`missing required standard property "${name}"`);
+            continue;
+        }
+        const standardTypes = schemaTypes(standardProps[name]);
+        const advertisedTypes = schemaTypes(advertisedProps[name]);
+        if (standardTypes.size > 0 && advertisedTypes.size > 0) {
+            const compatible = [...standardTypes].every((st) => {
+                if (advertisedTypes.has(st)) {
+                    return true;
+                }
+                // `integer` is a refinement of `number`: a standard `number` is
+                // satisfied by an advertised `integer`, and vice versa is acceptable.
+                if (st === "number" && advertisedTypes.has("integer")) {
+                    return true;
+                }
+                if (st === "integer" && advertisedTypes.has("number")) {
+                    notes.push(`property "${name}" widens standard integer to number`);
+                    return true;
+                }
+                return false;
+            });
+            if (!compatible) {
+                violations.push(`property "${name}" type ${[...advertisedTypes].join("|")} is incompatible with standard ${[...standardTypes].join("|")}`);
+                continue;
+            }
+        }
+        matchedRequired.push(name);
+    }
+    // Record advertised-only properties as informational coverage notes.
+    if (advertisedNames) {
+        const standardNames = new Set(Object.keys(standardProps));
+        for (const name of advertisedNames) {
+            if (!standardNames.has(name)) {
+                notes.push(`advertises non-standard property "${name}"`);
+            }
+        }
+    }
+    return { conformant: violations.length === 0, matchedRequired, violations, notes };
+}

package/dist/src/certification/mock-upstream.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A real, in-process streamable-HTTP mock of the honua `/mcp` operator surface.
+ *
+ * The certification harness connects to this over the SAME client transport it
+ * uses for a live server (`StreamableHTTPClientTransport`), so the offline CI
+ * path exercises the identical connect/negotiate/tools-call code as the remote
+ * path — only the upstream is swapped for a deterministic fixture.
+ *
+ * Auth is enforced per request: the listener parses the bearer token / API key
+ * and attaches `req.auth` when present. Requests without a credential reach the
+ * operator server as unauthenticated, so the certifier's auth-contract pass sees
+ * the same structured `unauthenticated` signal a real deployment would emit.
+ */
+export interface MockUpstreamOptions {
+    /** Bearer token the mock accepts; default `mock-cert-token`. */
+    authToken?: string;
+    /** Whether tools/list and resources/list paginate (default true). */
+    paginate?: boolean;
+}
+export interface MockUpstream {
+    /** Absolute URL of the mock `/mcp` endpoint (loopback, ephemeral port). */
+    url: string;
+    /** Bearer token the mock accepts. */
+    authToken: string;
+    close(): Promise<void>;
+}
+/** Start the mock operator upstream and resolve once it is listening. */
+export declare function startMockUpstream(options?: MockUpstreamOptions): Promise<MockUpstream>;
+//# sourceMappingURL=mock-upstream.d.ts.map

package/dist/src/certification/mock-upstream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-upstream.d.ts","sourceRoot":"","sources":["../../../src/certification/mock-upstream.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAC;IACZ,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAcD,yEAAyE;AACzE,wBAAsB,iBAAiB,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,YAAY,CAAC,CA4BhG"}