@honua/mcp-server 0.1.13 → 0.1.15

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

@@ -0,0 +1,99 @@
+/**
+ * honua-server MCP tool roster (`docs/gis/data/mcp-tool-roster.v1.json`) and the
+ * `roster-parity` check the certifier runs against a live `/mcp`.
+ *
+ * The roster is the server's own generated list of every tool name its composed
+ * registry can advertise. It is the authority this repo's catalogs and corpora
+ * are checked against, so a retired tool (e.g. `honua_propose_operation`) can no
+ * longer linger here after the server drops it.
+ *
+ * The roster is read BY SERVER SHA: the same honua-server commit the pinned
+ * candidate image was built from (`ADMIN_LOCAL_SERVER_SHA` in the installer lane). When the file does
+ * not exist at that sha (the server change that adds it has not reached the pin
+ * yet), the check reports `blocked` with the reason. It never passes without a
+ * roster to compare against.
+ */
+/** Path of the roster inside the honua-server repository. */
+export declare const ROSTER_REPO_PATH = "docs/gis/data/mcp-tool-roster.v1.json";
+/** Raw-content URL of the roster at a honua-server commit. */
+export declare function rosterUrl(serverSha: string): string;
+export type RosterViewName = "default" | "setup" | "configure" | "operate" | "analyze";
+export declare const ROSTER_VIEW_NAMES: readonly RosterViewName[];
+/** Shape of `mcp-tool-roster.v1.json` (fields this repo consumes). */
+export interface McpToolRoster {
+    serverSha: string | null;
+    /** Hand-authored IMcpTool names, every capability gate enabled. */
+    static: string[];
+    /** `honua_admin_*` tools the default production composition publishes. */
+    projectedAdmin: string[];
+    /** Subset of projectedAdmin that registers only with a durable proposal store (Redis). */
+    requiresDurableControlPlane: string[];
+    views: Record<RosterViewName, string[]>;
+    /** Names the server no longer advertises. */
+    retired: string[];
+}
+export type RosterResolution = {
+    status: "loaded";
+    roster: McpToolRoster;
+    source: string;
+} | {
+    status: "blocked";
+    reason: string;
+    source: string;
+};
+/** Validate and normalize a parsed roster document. Throws on a malformed shape. */
+export declare function parseRoster(raw: unknown): McpToolRoster;
+/** Every name the server can advertise: `static ∪ projectedAdmin`. */
+export declare function advertisableNames(roster: McpToolRoster): Set<string>;
+export declare const VENDORED_ROSTER_DIR: URL;
+/** The honua-server sha the vendored roster provenance is pinned to, if any. */
+export declare function vendoredRosterPin(): string | null;
+/** Load the vendored roster, or report why it is blocked. */
+export declare function loadVendoredRoster(): RosterResolution;
+export interface ResolveRosterOptions {
+    env?: NodeJS.ProcessEnv;
+    fetchFn?: typeof fetch;
+}
+/**
+ * Resolve the roster a live certification compares against:
+ *   1. `HONUA_MCP_ROSTER_FILE` — an explicit local roster file;
+ *   2. the server sha `HONUA_MCP_ROSTER_SERVER_SHA` (the candidate's
+ *      `ADMIN_LOCAL_SERVER_SHA` in the installer lane), defaulting to the vendored
+ *      working-contract provenance pin for offline certification:
+ *      the vendored copy when it is pinned to that sha, otherwise the raw file
+ *      fetched from honua-server at that sha.
+ * Any failure resolves to `blocked` with the reason, never to a pass.
+ */
+export declare function resolveRoster(options?: ResolveRosterOptions): Promise<RosterResolution>;
+export interface RosterParityOptions {
+    /**
+     * Whether the certified topology has a durable control plane (Redis). When
+     * false, the `requiresDurableControlPlane` names may legitimately be absent.
+     */
+    durableControlPlane: boolean;
+}
+export interface RosterParityResult {
+    ok: boolean;
+    /** Advertised names the roster does not list in `static ∪ projectedAdmin`. */
+    unrostered: string[];
+    /** `views.default` names the surface did not advertise. */
+    missingDefault: string[];
+    /** Retired names the surface still advertises. */
+    retiredAdvertised: string[];
+    /** `views.default` names absent only because the topology lacks a durable control plane. */
+    tolerated: string[];
+}
+/**
+ * Compare a surface's advertised `tools/list` names with the roster:
+ *   - every advertised name ∈ `static ∪ projectedAdmin`;
+ *   - every `views.default` name is advertised (the certifier connects without a
+ *     workflow-view selector, i.e. the default view);
+ *   - no `retired` name is advertised;
+ *   - without a durable control plane, `requiresDurableControlPlane` names may be absent.
+ */
+export declare function checkRosterParity(advertised: Iterable<string>, roster: McpToolRoster, options: RosterParityOptions): RosterParityResult;
+/** One-line human summary of a parity result. */
+export declare function describeRosterParity(result: RosterParityResult, advertisedCount: number): string;
+/** Whether the certified topology has a durable control plane (default: yes). */
+export declare function resolveDurableControlPlane(env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=roster.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"roster.d.ts","sourceRoot":"","sources":["../../../src/certification/roster.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AAEH,6DAA6D;AAC7D,eAAO,MAAM,gBAAgB,0CAA0C,CAAC;AAExE,8DAA8D;AAC9D,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,OAAO,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;AAEvF,eAAO,MAAM,iBAAiB,EAAE,SAAS,cAAc,EAA4D,CAAC;AAEpH,sEAAsE;AACtE,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,mEAAmE;IACnE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,0EAA0E;IAC1E,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,0FAA0F;IAC1F,2BAA2B,EAAE,MAAM,EAAE,CAAC;IACtC,KAAK,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,EAAE,CAAC,CAAC;IACxC,6CAA6C;IAC7C,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC3D;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAS1D,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,CAqBvD;AAED,sEAAsE;AACtE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,GAAG,CAAC,MAAM,CAAC,CAEpE;AAsBD,eAAO,MAAM,mBAAmB,KAA6B,CAAC;AAE9D,gFAAgF;AAChF,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,IAAI,CAOjD;AAED,6DAA6D;AAC7D,wBAAgB,kBAAkB,IAAI,gBAAgB,CAgBrD;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAwDjG;AAED,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,8EAA8E;IAC9E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,2DAA2D;IAC3D,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,kDAAkD;IAClD,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,4FAA4F;IAC5F,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,EAC5B,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CA2BpB;AAED,iDAAiD;AACjD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM,CAehG;AAED,iFAAiF;AACjF,wBAAgB,0BAA0B,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAGxF"}

package/dist/src/certification/roster.js

@@ -0,0 +1,233 @@
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+/**
+ * honua-server MCP tool roster (`docs/gis/data/mcp-tool-roster.v1.json`) and the
+ * `roster-parity` check the certifier runs against a live `/mcp`.
+ *
+ * The roster is the server's own generated list of every tool name its composed
+ * registry can advertise. It is the authority this repo's catalogs and corpora
+ * are checked against, so a retired tool (e.g. `honua_propose_operation`) can no
+ * longer linger here after the server drops it.
+ *
+ * The roster is read BY SERVER SHA: the same honua-server commit the pinned
+ * candidate image was built from (`ADMIN_LOCAL_SERVER_SHA` in the installer lane). When the file does
+ * not exist at that sha (the server change that adds it has not reached the pin
+ * yet), the check reports `blocked` with the reason. It never passes without a
+ * roster to compare against.
+ */
+/** Path of the roster inside the honua-server repository. */
+export const ROSTER_REPO_PATH = "docs/gis/data/mcp-tool-roster.v1.json";
+/** Raw-content URL of the roster at a honua-server commit. */
+export function rosterUrl(serverSha) {
+    return `https://raw.githubusercontent.com/honua-io/honua-server/${serverSha}/${ROSTER_REPO_PATH}`;
+}
+export const ROSTER_VIEW_NAMES = ["default", "setup", "configure", "operate", "analyze"];
+function readNameArray(value, field) {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+        throw new Error(`roster field "${field}" must be an array of tool-name strings`);
+    }
+    return [...value];
+}
+/** Validate and normalize a parsed roster document. Throws on a malformed shape. */
+export function parseRoster(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        throw new Error("roster must be a JSON object");
+    }
+    const doc = raw;
+    const views = doc.views;
+    if (typeof views !== "object" || views === null || Array.isArray(views)) {
+        throw new Error('roster field "views" must be an object');
+    }
+    const viewMap = {};
+    for (const view of ROSTER_VIEW_NAMES) {
+        viewMap[view] = readNameArray(views[view], `views.${view}`);
+    }
+    return {
+        serverSha: typeof doc.serverSha === "string" ? doc.serverSha : null,
+        static: readNameArray(doc.static, "static"),
+        projectedAdmin: readNameArray(doc.projectedAdmin, "projectedAdmin"),
+        requiresDurableControlPlane: readNameArray(doc.requiresDurableControlPlane, "requiresDurableControlPlane"),
+        views: viewMap,
+        retired: readNameArray(doc.retired, "retired"),
+    };
+}
+/** Every name the server can advertise: `static ∪ projectedAdmin`. */
+export function advertisableNames(roster) {
+    return new Set([...roster.static, ...roster.projectedAdmin]);
+}
+/**
+ * Vendored copy of the roster, kept beside its provenance so the offline unit
+ * test can check this repo's catalog without network access. Probed from both
+ * the compiled (`dist/src/certification`) and source (`src/certification`)
+ * layouts.
+ */
+function resolveVendoredRosterDir() {
+    const candidates = [
+        "../../../certification/honua-server-mcp-roster/",
+        "../../certification/honua-server-mcp-roster/",
+    ];
+    for (const candidate of candidates) {
+        const url = new URL(candidate, import.meta.url);
+        if (existsSync(new URL("PROVENANCE.md", url))) {
+            return url;
+        }
+    }
+    return new URL(candidates[0], import.meta.url);
+}
+export const VENDORED_ROSTER_DIR = resolveVendoredRosterDir();
+/** The honua-server sha the vendored roster provenance is pinned to, if any. */
+export function vendoredRosterPin() {
+    const provenance = new URL("PROVENANCE.md", VENDORED_ROSTER_DIR);
+    if (!existsSync(provenance)) {
+        return null;
+    }
+    const match = /Server commit:\*\* `([0-9a-f]{40})`/.exec(readFileSync(provenance, "utf8"));
+    return match ? match[1] : null;
+}
+/** Load the vendored roster, or report why it is blocked. */
+export function loadVendoredRoster() {
+    const pin = vendoredRosterPin();
+    const file = new URL("mcp-tool-roster.v1.json", VENDORED_ROSTER_DIR);
+    const source = `vendored ${fileURLToPath(file)}${pin ? ` (honua-server@${pin})` : ""}`;
+    if (!existsSync(file)) {
+        return {
+            status: "blocked",
+            source,
+            reason: `no vendored roster: ${ROSTER_REPO_PATH} does not exist at the pinned honua-server@${pin ?? "(unpinned)"} yet`,
+        };
+    }
+    try {
+        return { status: "loaded", roster: parseRoster(JSON.parse(readFileSync(file, "utf8"))), source };
+    }
+    catch (err) {
+        return { status: "blocked", source, reason: `vendored roster is malformed: ${errorMessage(err)}` };
+    }
+}
+/**
+ * Resolve the roster a live certification compares against:
+ *   1. `HONUA_MCP_ROSTER_FILE` — an explicit local roster file;
+ *   2. the server sha `HONUA_MCP_ROSTER_SERVER_SHA` (the candidate's
+ *      `ADMIN_LOCAL_SERVER_SHA` in the installer lane), defaulting to the vendored
+ *      working-contract provenance pin for offline certification:
+ *      the vendored copy when it is pinned to that sha, otherwise the raw file
+ *      fetched from honua-server at that sha.
+ * Any failure resolves to `blocked` with the reason, never to a pass.
+ */
+export async function resolveRoster(options = {}) {
+    const env = options.env ?? process.env;
+    const file = env.HONUA_MCP_ROSTER_FILE?.trim();
+    if (file) {
+        try {
+            return { status: "loaded", roster: parseRoster(JSON.parse(readFileSync(file, "utf8"))), source: file };
+        }
+        catch (err) {
+            return { status: "blocked", source: file, reason: `roster file unreadable: ${errorMessage(err)}` };
+        }
+    }
+    const sha = env.HONUA_MCP_ROSTER_SERVER_SHA?.trim() || vendoredRosterPin();
+    if (!sha) {
+        return {
+            status: "blocked",
+            source: "(none)",
+            reason: "no honua-server sha to read the roster at (set HONUA_MCP_ROSTER_SERVER_SHA)",
+        };
+    }
+    if (!/^[0-9a-f]{7,40}$/.test(sha)) {
+        return { status: "blocked", source: sha, reason: `HONUA_MCP_ROSTER_SERVER_SHA is not a commit sha: ${sha}` };
+    }
+    if (vendoredRosterPin() === sha) {
+        const vendored = loadVendoredRoster();
+        if (vendored.status === "loaded") {
+            return vendored;
+        }
+    }
+    const url = rosterUrl(sha);
+    const fetchFn = options.fetchFn ?? fetch;
+    // honua-server may be private to this workflow's token; a read token makes a
+    // 404 mean "absent at that sha" rather than "not visible".
+    const token = env.HONUA_MCP_ROSTER_TOKEN?.trim();
+    try {
+        const response = await fetchFn(url, {
+            redirect: "follow",
+            ...(token ? { headers: { Authorization: `token ${token}` } } : {}),
+        });
+        if (response.status === 404) {
+            return {
+                status: "blocked",
+                source: url,
+                reason: token
+                    ? `${ROSTER_REPO_PATH} does not exist at honua-server@${sha} (the roster has not reached the pinned server sha yet)`
+                    : `${ROSTER_REPO_PATH} not found at honua-server@${sha}: absent at that sha, or not readable without HONUA_MCP_ROSTER_TOKEN`,
+            };
+        }
+        if (!response.ok) {
+            return { status: "blocked", source: url, reason: `roster fetch failed with HTTP ${response.status}` };
+        }
+        return { status: "loaded", roster: parseRoster(await response.json()), source: url };
+    }
+    catch (err) {
+        return { status: "blocked", source: url, reason: `roster fetch failed: ${errorMessage(err)}` };
+    }
+}
+/**
+ * Compare a surface's advertised `tools/list` names with the roster:
+ *   - every advertised name ∈ `static ∪ projectedAdmin`;
+ *   - every `views.default` name is advertised (the certifier connects without a
+ *     workflow-view selector, i.e. the default view);
+ *   - no `retired` name is advertised;
+ *   - without a durable control plane, `requiresDurableControlPlane` names may be absent.
+ */
+export function checkRosterParity(advertised, roster, options) {
+    const advertisedSet = new Set(advertised);
+    const known = advertisableNames(roster);
+    const durableOnly = new Set(roster.requiresDurableControlPlane);
+    const retired = new Set(roster.retired);
+    const unrostered = [...advertisedSet].filter((name) => !known.has(name) && !retired.has(name)).sort();
+    const retiredAdvertised = [...advertisedSet].filter((name) => retired.has(name)).sort();
+    const missingDefault = [];
+    const tolerated = [];
+    for (const name of roster.views.default) {
+        if (advertisedSet.has(name))
+            continue;
+        if (!options.durableControlPlane && durableOnly.has(name)) {
+            tolerated.push(name);
+        }
+        else {
+            missingDefault.push(name);
+        }
+    }
+    missingDefault.sort();
+    tolerated.sort();
+    return {
+        ok: unrostered.length === 0 && missingDefault.length === 0 && retiredAdvertised.length === 0,
+        unrostered,
+        missingDefault,
+        retiredAdvertised,
+        tolerated,
+    };
+}
+/** One-line human summary of a parity result. */
+export function describeRosterParity(result, advertisedCount) {
+    if (result.ok) {
+        const tolerated = result.tolerated.length > 0
+            ? `; ${result.tolerated.length} durable-control-plane tool(s) absent on this topology: ${result.tolerated.join(", ")}`
+            : "";
+        return `all ${advertisedCount} advertised tools are rostered, views.default is fully advertised, no retired tool is advertised${tolerated}`;
+    }
+    const parts = [];
+    if (result.retiredAdvertised.length > 0)
+        parts.push(`retired tool(s) advertised: ${result.retiredAdvertised.join(", ")}`);
+    if (result.unrostered.length > 0)
+        parts.push(`advertised but not in roster: ${result.unrostered.join(", ")}`);
+    if (result.missingDefault.length > 0)
+        parts.push(`views.default tool(s) not advertised: ${result.missingDefault.join(", ")}`);
+    return parts.join("; ");
+}
+/** Whether the certified topology has a durable control plane (default: yes). */
+export function resolveDurableControlPlane(env = process.env) {
+    const raw = (env.HONUA_MCP_CERT_TOPOLOGY ?? "durable").trim().toLowerCase();
+    return raw !== "redis-off" && raw !== "ephemeral";
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/src/certification/round-trip-target.d.ts

@@ -0,0 +1,45 @@
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { RoundTripEnv } from "./fixtures.js";
+/**
+ * Round-trip target discovery for a freshly booted candidate.
+ *
+ * The read-only round trips need a published layer. The offline mock seeds
+ * `svc-parks`, but a fresh `honua admin install local` candidate publishes
+ * nothing under that id. Setting `HONUA_MCP_SERVICE_ID=discover` makes the
+ * certifier ask the candidate itself (`honua_list_layers`) and bind the round
+ * trips to the first published layer. When the candidate serves no layer the
+ * `round-trip-target` contract is `blocked`: the evidence could not be gathered,
+ * so the summary cannot pass, and the service-bound tools are not called with a
+ * made-up id.
+ */
+/** Sentinel value of `HONUA_MCP_SERVICE_ID` that asks for discovery. */
+export declare const DISCOVER_SERVICE_ID = "discover";
+/** The tool the target is discovered from. */
+export declare const LIST_LAYERS_TOOL = "honua_list_layers";
+/** Round-trip fixtures that address a published service/layer. */
+export declare const SERVICE_BOUND_TOOLS: readonly string[];
+export type RoundTripTargetResolution = {
+    status: "passed";
+    serviceId: string;
+    layerId: number;
+    detail: string;
+} | {
+    status: "blocked";
+    detail: string;
+};
+/** Whether the resolved round-trip env asks for discovery. */
+export declare function wantsDiscovery(env: RoundTripEnv): boolean;
+/**
+ * Pick the first published layer from a `honua_list_layers` payload
+ * (`structuredContent`, or the JSON text content when no structured output is
+ * returned). Accepts camelCase and snake_case identifiers.
+ */
+export declare function firstPublishedLayer(payload: unknown): {
+    serviceId: string;
+    layerId: number;
+} | undefined;
+/** Ask the candidate for its first published layer. Never throws. */
+export declare function discoverRoundTripTarget(client: Pick<Client, "callTool">, advertisedNames: Set<string>): Promise<RoundTripTargetResolution>;
+/** Drop the round-trip fixtures that would address an undiscovered service. */
+export declare function withoutServiceBoundInputs(inputs: Record<string, Record<string, unknown>>): Record<string, Record<string, unknown>>;
+//# sourceMappingURL=round-trip-target.d.ts.map

package/dist/src/certification/round-trip-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"round-trip-target.d.ts","sourceRoot":"","sources":["../../../src/certification/round-trip-target.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD;;;;;;;;;;;GAWG;AAEH,wEAAwE;AACxE,eAAO,MAAM,mBAAmB,aAAa,CAAC;AAE9C,8CAA8C;AAC9C,eAAO,MAAM,gBAAgB,sBAAsB,CAAC;AAEpD,kEAAkE;AAClE,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAOhD,CAAC;AAEF,MAAM,MAAM,yBAAyB,GACjC;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACxE;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1C,8DAA8D;AAC9D,wBAAgB,cAAc,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAEzD;AAWD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAoBxG;AAsBD,qEAAqE;AACrE,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,UAAU,CAAC,EAChC,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,GAC3B,OAAO,CAAC,yBAAyB,CAAC,CAkCpC;AAED,+EAA+E;AAC/E,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAC9C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAMzC"}

package/dist/src/certification/round-trip-target.js

@@ -0,0 +1,122 @@
+/**
+ * Round-trip target discovery for a freshly booted candidate.
+ *
+ * The read-only round trips need a published layer. The offline mock seeds
+ * `svc-parks`, but a fresh `honua admin install local` candidate publishes
+ * nothing under that id. Setting `HONUA_MCP_SERVICE_ID=discover` makes the
+ * certifier ask the candidate itself (`honua_list_layers`) and bind the round
+ * trips to the first published layer. When the candidate serves no layer the
+ * `round-trip-target` contract is `blocked`: the evidence could not be gathered,
+ * so the summary cannot pass, and the service-bound tools are not called with a
+ * made-up id.
+ */
+/** Sentinel value of `HONUA_MCP_SERVICE_ID` that asks for discovery. */
+export const DISCOVER_SERVICE_ID = "discover";
+/** The tool the target is discovered from. */
+export const LIST_LAYERS_TOOL = "honua_list_layers";
+/** Round-trip fixtures that address a published service/layer. */
+export const SERVICE_BOUND_TOOLS = [
+    "honua_describe_layer",
+    "honua_count_features",
+    "honua_get_extent",
+    "honua_statistics",
+    "honua_query_features",
+    "honua_render_map",
+];
+/** Whether the resolved round-trip env asks for discovery. */
+export function wantsDiscovery(env) {
+    return env.serviceId === DISCOVER_SERVICE_ID;
+}
+function asLayerId(value) {
+    const n = typeof value === "string" && value.trim() !== "" ? Number(value) : value;
+    return typeof n === "number" && Number.isInteger(n) && n >= 0 ? n : undefined;
+}
+function asServiceId(value) {
+    return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+/**
+ * Pick the first published layer from a `honua_list_layers` payload
+ * (`structuredContent`, or the JSON text content when no structured output is
+ * returned). Accepts camelCase and snake_case identifiers.
+ */
+export function firstPublishedLayer(payload) {
+    if (!payload || typeof payload !== "object") {
+        return undefined;
+    }
+    const layers = payload.layers;
+    if (!Array.isArray(layers)) {
+        return undefined;
+    }
+    for (const layer of layers) {
+        if (!layer || typeof layer !== "object") {
+            continue;
+        }
+        const l = layer;
+        const serviceId = asServiceId(l.serviceId ?? l.service_id);
+        const layerId = asLayerId(l.layerId ?? l.layer_id);
+        if (serviceId && layerId !== undefined) {
+            return { serviceId, layerId };
+        }
+    }
+    return undefined;
+}
+function payloadOf(result) {
+    if (result.structuredContent !== undefined) {
+        return result.structuredContent;
+    }
+    if (Array.isArray(result.content)) {
+        for (const part of result.content) {
+            const text = part.type === "text" ? part.text : undefined;
+            if (typeof text === "string") {
+                try {
+                    return JSON.parse(text);
+                }
+                catch {
+                    // not JSON; keep looking
+                }
+            }
+        }
+    }
+    return undefined;
+}
+/** Ask the candidate for its first published layer. Never throws. */
+export async function discoverRoundTripTarget(client, advertisedNames) {
+    if (!advertisedNames.has(LIST_LAYERS_TOOL)) {
+        return {
+            status: "blocked",
+            detail: `${LIST_LAYERS_TOOL} is not advertised, so no published layer can be discovered`,
+        };
+    }
+    try {
+        const result = (await client.callTool({ name: LIST_LAYERS_TOOL, arguments: {} }));
+        if (result.isError) {
+            return { status: "blocked", detail: `${LIST_LAYERS_TOOL} returned isError=true; no published layer discovered` };
+        }
+        const layer = firstPublishedLayer(payloadOf(result));
+        if (!layer) {
+            return {
+                status: "blocked",
+                detail: `the candidate serves no published layer (${LIST_LAYERS_TOOL} returned none); publish a service before certifying the round trips`,
+            };
+        }
+        return {
+            status: "passed",
+            ...layer,
+            detail: `round trips bound to ${layer.serviceId} layer ${layer.layerId} (first layer from ${LIST_LAYERS_TOOL})`,
+        };
+    }
+    catch (err) {
+        return {
+            status: "blocked",
+            detail: `${LIST_LAYERS_TOOL} failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+/** Drop the round-trip fixtures that would address an undiscovered service. */
+export function withoutServiceBoundInputs(inputs) {
+    const kept = { ...inputs };
+    for (const name of SERVICE_BOUND_TOOLS) {
+        delete kept[name];
+    }
+    return kept;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/certification/run.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,mBAAmB,EAAW,MAAM,gBAAgB,CAAC;AAEnE,OAAO,EAAE,KAAK,mBAAmB,EAA2B,MAAM,aAAa,CAAC;AAEhF;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED,wBAAsB,gBAAgB,CAAC,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAI7F;AAED,8DAA8D;AAC9D,wBAAsB,aAAa,CACjC,MAAM,EAAE,mBAAmB,EAC3B,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAAC,mBAAmB,CAAC,CAe9B;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,MAAM,EAAE,mBAAmB,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI,CAGtF"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/certification/run.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,mBAAmB,EAAW,MAAM,gBAAgB,CAAC;AAGnE,OAAO,EAAE,KAAK,mBAAmB,EAA2B,MAAM,aAAa,CAAC;AAEhF;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED,wBAAsB,gBAAgB,CAAC,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAI7F;AAED,8DAA8D;AAC9D,wBAAsB,aAAa,CACjC,MAAM,EAAE,mBAAmB,EAC3B,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAAC,mBAAmB,CAAC,CAsB9B;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,MAAM,EAAE,mBAAmB,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI,CAGtF"}

package/dist/src/certification/run.js

@@ -1,6 +1,7 @@
 import { writeFileSync } from "node:fs";
 import { certify } from "./certifier.js";
 import { renderMarkdown } from "./report.js";
+import { resolveDurableControlPlane, resolveRoster } from "./roster.js";
 import { openCertificationTarget } from "./target.js";
 export async function runCertification(options = {}) {
     const env = options.env ?? process.env;
@@ -10,6 +11,11 @@ export async function runCertification(options = {}) {
 /** Certify an already-opened target, closing it when done. */
 export async function certifyTarget(target, env = process.env) {
     try {
+        // Roster parity is a product-surface contract: only a live honua /mcp
+        // (directly or through the stdio proxy) is held to the server roster.
+        const roster = target.backend === "live" && (target.mode === "remote" || target.mode === "stdio-proxy")
+            ? await resolveRoster({ env })
+            : undefined;
         return await certify({
             client: target.client,
             targetMode: target.mode,
@@ -19,6 +25,7 @@ export async function certifyTarget(target, env = process.env) {
             authMode: target.authMode,
             connectUnauthenticated: target.supportsUnauthenticatedPass ? () => target.connectUnauthenticated() : undefined,
             env,
+            ...(roster ? { roster, durableControlPlane: resolveDurableControlPlane(env) } : {}),
         });
     }
     finally {

package/dist/src/eval/northstar-corpus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"northstar-corpus.d.ts","sourceRoot":"","sources":["../../../src/eval/northstar-corpus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAiF3C,eAAO,MAAM,gBAAgB,EAAE,QAAQ,EAyHtC,CAAC"}
+{"version":3,"file":"northstar-corpus.d.ts","sourceRoot":"","sources":["../../../src/eval/northstar-corpus.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAkF3C,eAAO,MAAM,gBAAgB,EAAE,QAAQ,EAyHtC,CAAC"}

package/dist/src/eval/northstar-corpus.js

@@ -1,3 +1,4 @@
+import { TYPED_PROPOSAL_TOOLS } from "./proposal-tools.js";
 /**
  * NORTH-STAR corpus — the P1 gate measure (honua-server #1948, MCP initiative P1.7).
  *
@@ -37,12 +38,13 @@
  * with `--driver bedrock` + `HONUA_MCP_REMOTE_URL=<server>/mcp` + credentials.
  */
 /**
- * The generic mutation escape-hatch. Every north-star workflow must compose the
- * structured lifecycle (plan → validate → execute → publish) rather than reach
- * for `honua_propose_operation`, so forbidding it turns "did the client use the
+ * The governed control-plane proposal roster (the typed tools that replaced the
+ * retired `honua_propose_operation`). Every north-star workflow must compose the
+ * structured lifecycle (plan → validate → execute → publish) rather than file a
+ * control-plane proposal, so forbidding the roster turns "did the client use the
  * intended workflow?" into a graded criterion.
  */
-const GENERIC_MUTATION_TOOL = "honua_propose_operation";
+const PROPOSAL_TOOLS = [...TYPED_PROPOSAL_TOOLS];
 /** A small, embedded address CSV for the geocode → publish workflow (10 rows). */
 const ADDRESS_CSV = [
     "name,street,city,state,zip",
@@ -71,7 +73,7 @@ const CSV_GEOCODE_PROMPT = `Here is a CSV of addresses. Geocode them and publish
 ${ADDRESS_CSV}
 \`\`\`
 
-Batch-geocode every row, ingest the geocoded points as a dataset, and publish that dataset as a hosted point service. Do not reach for a raw propose_operation.`;
+Batch-geocode every row, ingest the geocoded points as a dataset, and publish that dataset as a hosted point service. Do not file a control-plane proposal (honua_propose_*).`;
 export const NORTHSTAR_CORPUS = [
     {
         id: "northstar-styled-map",
@@ -80,13 +82,13 @@ export const NORTHSTAR_CORPUS = [
         prompt: "Find all parcels within 500 m of a flood zone and produce a styled map of them. " +
             "Resolve the parcels and flood-zone layers, plan and run the proximity analysis as a " +
             "governed job, publish the result as a new layer, style it, and render a map. Use the " +
-            "structured analysis lifecycle — do not reach for a raw propose_operation.",
+            "structured analysis lifecycle — do not file a control-plane proposal (honua_propose_*).",
         criteria: {
             // Load-bearing arc of the workflow: ground the entities, execute the plan,
             // publish the job artifact to a layer, and render a map of it.
             requiredTools: ["honua_resolve_entity", "honua_execute_plan", "honua_publish_result", "honua_render_map"],
             expectedToolSequence: ["honua_resolve_entity", "honua_execute_plan", "honua_publish_result", "honua_render_map"],
-            forbiddenTools: [GENERIC_MUTATION_TOOL],
+            forbiddenTools: PROPOSAL_TOOLS,
         },
         script: [
             { tool: "honua_resolve_entity", args: { text: "parcels", entityType: "layer" } },
@@ -121,7 +123,7 @@ export const NORTHSTAR_CORPUS = [
             // ingest the resulting points → publish the source table as a service.
             requiredTools: ["honua_geocode_addresses", "honua_ingest_dataset", "honua_publish_service"],
             expectedToolSequence: ["honua_geocode_addresses", "honua_ingest_dataset", "honua_publish_service"],
-            forbiddenTools: [GENERIC_MUTATION_TOOL],
+            forbiddenTools: PROPOSAL_TOOLS,
         },
         script: [
             { tool: "honua_geocode_addresses", args: { addresses: ADDRESS_ROWS } },
@@ -153,7 +155,7 @@ export const NORTHSTAR_CORPUS = [
         prompt: "Buffer highways by 100 m, intersect the buffers with wetlands, and give me summary " +
             "statistics for the overlap. Run it as a job and report progress. Ground the goal into " +
             "an analysis plan, validate it, then execute it as a governed job and report the results " +
-            "the job produces. Do not reach for a raw propose_operation.",
+            "the job produces. Do not file a control-plane proposal (honua_propose_*).",
         criteria: {
             // Plan entry → validate → execute-as-job. The answer must carry evidence
             // that the JOB path was used and its results read back — kept loose (the
@@ -166,7 +168,7 @@ export const NORTHSTAR_CORPUS = [
                 "honua_validate_plan",
                 "honua_execute_plan",
             ],
-            forbiddenTools: [GENERIC_MUTATION_TOOL],
+            forbiddenTools: PROPOSAL_TOOLS,
             answerMustInclude: ["job"],
         },
         script: [

package/dist/src/eval/operator-corpus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operator-corpus.d.ts","sourceRoot":"","sources":["../../../src/eval/operator-corpus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AA2D3C,eAAO,MAAM,eAAe,EAAE,QAAQ,EAmJrC,CAAC"}
+{"version":3,"file":"operator-corpus.d.ts","sourceRoot":"","sources":["../../../src/eval/operator-corpus.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AA+D3C,eAAO,MAAM,eAAe,EAAE,QAAQ,EAmJrC,CAAC"}