@honua/mcp-server 0.0.10-alpha.0 → 0.1.0-beta.0

package/dist/src/certification/contracts.js

@@ -0,0 +1,245 @@
+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)}"`,
+        ],
+    };
+}
+/** Documented job states, ordered by lifecycle rank (terminal states are highest). */
+export const JOB_STATE_RANK = {
+    Submitted: 0,
+    Queued: 0,
+    Running: 1,
+    Succeeded: 2,
+    Failed: 2,
+    Cancelled: 2,
+};
+const TERMINAL_JOB_STATES = new Set(["Succeeded", "Failed", "Cancelled"]);
+/**
+ * mutating-round-trip contract: an insert must be observable, an update must be
+ * reflected, and a delete must remove the feature — the full edit lifecycle
+ * verified against the surface's own read path.
+ */
+export function checkFeatureRoundTrip(obs) {
+    const errors = [];
+    if (obs.insertedObjectId === undefined) {
+        errors.push("insert did not return a new objectId");
+    }
+    if (!obs.presentAfterInsert) {
+        errors.push("inserted feature was not observable via a follow-up query");
+    }
+    if (obs.attributeAfterUpdate !== obs.expectedAttribute) {
+        errors.push(`updated attribute did not round-trip (expected ${JSON.stringify(obs.expectedAttribute)}, read ${JSON.stringify(obs.attributeAfterUpdate)})`);
+    }
+    if (!obs.absentAfterDelete) {
+        errors.push("feature was still observable after delete");
+    }
+    return { ok: errors.length === 0, errors };
+}
+/**
+ * async-job-lifecycle contract: an execute → poll(honua://jobs/{id}) → fetch-result
+ * flow must follow the documented state machine — statuses are all recognized,
+ * rank never regresses, progress is monotonic within [0,1], the job terminates
+ * (Succeeded here), and the result package is retrievable.
+ */
+export function checkJobLifecycle(obs) {
+    const errors = [];
+    const allStatuses = [obs.initialStatus, ...obs.polledStatuses, obs.finalStatus];
+    let lastRank = -1;
+    for (const status of allStatuses) {
+        const rank = JOB_STATE_RANK[status];
+        if (rank === undefined) {
+            errors.push(`unrecognized job state "${status}" (not in the documented state machine)`);
+            continue;
+        }
+        if (rank < lastRank) {
+            errors.push(`job state regressed from rank ${lastRank} to "${status}" (rank ${rank})`);
+        }
+        lastRank = rank;
+    }
+    let lastFraction = -1;
+    for (const fraction of obs.progressFractions) {
+        if (typeof fraction !== "number" || Number.isNaN(fraction) || fraction < 0 || fraction > 1) {
+            errors.push(`progress fraction ${String(fraction)} is out of the documented [0,1] range`);
+            continue;
+        }
+        if (fraction < lastFraction) {
+            errors.push(`progress fraction regressed from ${lastFraction} to ${fraction}`);
+        }
+        lastFraction = fraction;
+    }
+    if (!TERMINAL_JOB_STATES.has(obs.finalStatus)) {
+        errors.push(`job did not reach a terminal state (ended "${obs.finalStatus}")`);
+    }
+    if (obs.finalStatus === "Succeeded" && !obs.resultReady) {
+        errors.push("job succeeded but no ready result package could be fetched");
+    }
+    return { ok: errors.length === 0, errors };
+}
+/**
+ * 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,45 @@
+/**
+ * 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>>;
+/** Target layer for the mutating round-trip + pagination contracts. */
+export interface EditTarget {
+    serviceId: string;
+    layerId: number;
+}
+/**
+ * Resolve the editable/pageable target for the deep contracts. Defaults to the
+ * offline mock's seeded `svc-parks` layer 0; override with
+ * `HONUA_MCP_EDIT_SERVICE_ID` / `HONUA_MCP_EDIT_LAYER_ID` (or the shared
+ * `HONUA_MCP_SERVICE_ID` / `HONUA_MCP_LAYER_ID`) to point a live mutating cert at
+ * a dedicated scratch service.
+ */
+export declare function resolveEditTarget(env?: NodeJS.ProcessEnv): EditTarget;
+/**
+ * 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,CAsC/F;AAED,uEAAuE;AACvE,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,UAAU,CAOlF;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,92 @@
+/**
+ * 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 {
+        // ── Platform-free standalone surface tools (issue #369). Round-tripped by the
+        // `standalone` cert target against a plain public FeatureServer fixture. The
+        // Honua-only style tools resolve to a structured "not available on this
+        // target" result (non-error) — certifying graceful degradation, not a crash.
+        honua_list_services: {},
+        honua_describe_layer: { serviceId, layerId },
+        honua_count_features: { serviceId, layerId },
+        honua_get_extent: { serviceId, layerId },
+        honua_statistics: { serviceId, layerId, statisticType: "count", onField: "OBJECTID" },
+        honua_explain_capability_gap: { capability: "query", protocol: "wmts" },
+        honua_get_style: {},
+        honua_apply_style_preset: { styleId: "topographic" },
+        // ── Honua-enhanced operator catalog tools (offline/remote/stdio-proxy targets).
+        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" },
+    };
+}
+/**
+ * Resolve the editable/pageable target for the deep contracts. Defaults to the
+ * offline mock's seeded `svc-parks` layer 0; override with
+ * `HONUA_MCP_EDIT_SERVICE_ID` / `HONUA_MCP_EDIT_LAYER_ID` (or the shared
+ * `HONUA_MCP_SERVICE_ID` / `HONUA_MCP_LAYER_ID`) to point a live mutating cert at
+ * a dedicated scratch service.
+ */
+export function resolveEditTarget(env = process.env) {
+    const base = resolveRoundTripEnv(env);
+    const serviceId = env.HONUA_MCP_EDIT_SERVICE_ID ?? base.serviceId;
+    const layerRaw = env.HONUA_MCP_EDIT_LAYER_ID;
+    const parsedLayer = layerRaw !== undefined ? Number.parseInt(layerRaw, 10) : Number.NaN;
+    const layerId = Number.isFinite(parsedLayer) && parsedLayer >= 0 ? parsedLayer : base.layerId;
+    return { serviceId, layerId };
+}
+/**
+ * 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,71 @@
+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[];
+}
+export interface ConformanceOptions {
+    /**
+     * Required standard properties this surface is permitted to omit because it is
+     * a documented, platform-gated degradation of the tool (see the SDK-local
+     * `PLATFORM_FREE_DEGRADATIONS` registry in `schema-index.ts`).
+     *
+     * A property listed here is a platform *binding* — an identifier that only has
+     * meaning against a Honua publishing/authoring surface (e.g. `apply_style_preset`
+     * requires `serviceId`+`layerId` to bind a preset onto a *published* layer via
+     * the server OGC API – Styles authoring surface, ADR-0048). A platform-free
+     * target has no such surface, so it degrades the tool to a non-error, client-side
+     * projection keyed on the taxonomy essence alone (e.g. `styleId`) and legitimately
+     * omits the binding identifiers.
+     *
+     * When a required standard property is absent AND listed here, it is recorded as
+     * a degradation note rather than a conformance violation. Everything else stays
+     * strict: unlisted required properties still fail, and type incompatibilities on
+     * properties the surface DOES advertise remain violations — degradation relaxes
+     * platform binding, never correctness on what is accepted.
+     */
+    shedRequired?: readonly 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, options?: ConformanceOptions): 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,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,UAAU,EACpB,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CAkEnB"}