@humwick/server 0.130.0 → 0.130.2

package/node_modules/@humwick/kernel/manifest-validation.ts

@@ -1,460 +0,0 @@
-import { z } from "zod";
-import type {
-  ConfigLayer,
-  EntityDecl,
-  EventName,
-  HostCommandDecl,
-  ModuleManifest,
-  OpDecl,
-  RawRouteDecl,
-  RetryPolicy,
-  WorkflowDecl,
-} from "./contract";
-import { matchesGrant, matchesModuleId } from "./identity-grammar";
-
-export interface ManifestValidationIssue {
-  path: string;
-  message: string;
-}
-
-export class ManifestValidationError extends Error {
-  constructor(readonly issues: readonly ManifestValidationIssue[]) {
-    super(`invalid module manifest:\n${issues.map((issue) => `- ${issue.path}: ${issue.message}`).join("\n")}`);
-    this.name = "ManifestValidationError";
-  }
-}
-
-const RESERVED_ENTITY_FIELDS = new Set(["scope", "version", "created_at", "updated_at"]);
-const CONFIG_LAYERS = new Set<ConfigLayer>(["defaults", "instance", "host", "tenant", "user"]);
-/** The only keys an op's `expose` block may carry — one per transport (K6b HTTP/MCP/CLI). */
-const EXPOSE_TARGETS = new Set(["http", "mcp", "cli"]);
-
-class Validator {
-  readonly issues: ManifestValidationIssue[] = [];
-
-  issue(path: string, message: string): void {
-    this.issues.push({ path, message });
-  }
-
-  nonEmptyString(value: unknown, path: string): value is string {
-    if (typeof value !== "string" || value.trim().length === 0) {
-      this.issue(path, "must be a non-empty string");
-      return false;
-    }
-    return true;
-  }
-
-  positiveInteger(value: unknown, path: string): boolean {
-    if (!Number.isSafeInteger(value) || (value as number) <= 0) {
-      this.issue(path, "must be a positive integer");
-      return false;
-    }
-    return true;
-  }
-
-  record(value: unknown, path: string): value is Record<string, unknown> {
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-      this.issue(path, "must be an object");
-      return false;
-    }
-    return true;
-  }
-
-  fn(value: unknown, path: string): boolean {
-    if (typeof value !== "function") {
-      this.issue(path, "must be a function");
-      return false;
-    }
-    return true;
-  }
-
-  schema(value: unknown, path: string): boolean {
-    if (!(value instanceof z.ZodType)) {
-      this.issue(path, "must be a Zod schema");
-      return false;
-    }
-    return true;
-  }
-
-  objectSchema(value: unknown, path: string): value is z.ZodObject {
-    if (!(value instanceof z.ZodObject)) {
-      this.issue(path, "must be a Zod object schema");
-      return false;
-    }
-    return true;
-  }
-
-  grant(value: unknown, path: string): void {
-    if (!this.nonEmptyString(value, path)) return;
-    if (!matchesGrant(value)) this.issue(path, "must use '<module>:read|write|admin' or 'command:<name>'");
-  }
-
-  finish(): void {
-    if (this.issues.length > 0) throw new ManifestValidationError(this.issues);
-  }
-}
-
-/** Runtime structural and cross-field validation for a module declaration. */
-export function assertValidManifest(value: unknown): asserts value is ModuleManifest {
-  const v = new Validator();
-  if (!v.record(value, "manifest")) return v.finish();
-
-  const idValid = v.nonEmptyString(value.id, "id");
-  if (idValid && !matchesModuleId(value.id)) {
-    v.issue("id", value.id === "command" ? "is reserved" : "must be kebab-case");
-  }
-  v.nonEmptyString(value.title, "title");
-  v.nonEmptyString(value.description, "description");
-
-  if (value.config !== undefined) validateConfig(value.config, "config", v);
-  if (value.entities !== undefined) validateRecordEntries(value.entities, "entities", v, validateEntity);
-  if (value.events !== undefined) validateEvents(value.events, idValid ? value.id as string : "", v);
-  if (value.ops !== undefined) validateRecordEntries(value.ops, "ops", v, validateOp);
-  if (value.ops !== undefined) validateHttpRouteCollisions(value.ops, v);
-  if (value.routes !== undefined) validateRoutes(value.routes, v);
-  if (value.workflows !== undefined) validateRecordEntries(value.workflows, "workflows", v, validateWorkflow);
-  if (value.commands !== undefined) validateRecordEntries(value.commands, "commands", v, validateCommand);
-  if (value.health !== undefined) validateHealth(value.health, "health", v);
-  if (value.secrets !== undefined) validateSecrets(value.secrets, v);
-  if (value.ui !== undefined) validateUi(value.ui, "ui", v);
-  if (value.agentContext !== undefined) validateAgentContext(value.agentContext, v);
-  if (value.data !== undefined) validateMigrations(value.data, v);
-
-  validateEmittedEvents(value, v);
-  v.finish();
-}
-
-function validateRecordEntries<T>(
-  value: unknown,
-  path: string,
-  v: Validator,
-  validate: (entry: T, path: string, v: Validator) => void,
-): void {
-  if (!v.record(value, path)) return;
-  for (const [name, entry] of Object.entries(value)) {
-    if (!v.nonEmptyString(name, `${path} key`)) continue;
-    validate(entry as T, `${path}.${name}`, v);
-  }
-}
-
-function validateConfig(value: unknown, path: string, v: Validator): void {
-  if (!v.record(value, path)) return;
-  const schema = value.schema;
-  const schemaValid = v.objectSchema(schema, `${path}.schema`);
-  const keys = schemaValid ? new Set(Object.keys(schema.shape)) : new Set<string>();
-
-  if (value.env !== undefined && v.record(value.env, `${path}.env`)) {
-    for (const [key, envName] of Object.entries(value.env)) {
-      if (schemaValid && !keys.has(key)) v.issue(`${path}.env.${key}`, "must name a config schema key");
-      v.nonEmptyString(envName, `${path}.env.${key}`);
-    }
-  }
-
-  if (value.overridableAt !== undefined && v.record(value.overridableAt, `${path}.overridableAt`)) {
-    for (const [key, layers] of Object.entries(value.overridableAt)) {
-      const layerPath = `${path}.overridableAt.${key}`;
-      if (schemaValid && !keys.has(key)) v.issue(layerPath, "must name a config schema key");
-      if (!Array.isArray(layers) || layers.length === 0) {
-        v.issue(layerPath, "must be a non-empty array of config layers");
-        continue;
-      }
-      for (const layer of layers) {
-        if (!CONFIG_LAYERS.has(layer as ConfigLayer)) v.issue(layerPath, `contains unknown layer '${String(layer)}'`);
-      }
-    }
-  }
-}
-
-function validateEntity(value: EntityDecl, path: string, v: Validator): void {
-  if (!v.record(value, path)) return;
-  const schemaValid = v.objectSchema(value.schema, `${path}.schema`);
-  const fields = schemaValid ? new Set(Object.keys(value.schema.shape)) : new Set<string>();
-  if (schemaValid) {
-    for (const field of fields) {
-      if (RESERVED_ENTITY_FIELDS.has(field)) v.issue(`${path}.schema.${field}`, "is kernel-owned and may not be declared");
-    }
-  }
-
-  if (value.key !== undefined && (!v.nonEmptyString(value.key, `${path}.key`) || (schemaValid && !fields.has(value.key)))) {
-    if (typeof value.key === "string" && value.key.length > 0) v.issue(`${path}.key`, "must name a schema field");
-  }
-  if (value.key === undefined && schemaValid && !fields.has("id")) v.issue(`${path}.schema`, "must contain the default 'id' key or declare key");
-
-  if (value.indexes !== undefined) {
-    if (!Array.isArray(value.indexes)) v.issue(`${path}.indexes`, "must be an array");
-    else for (const [index, fieldsOrField] of value.indexes.entries()) {
-      const indexFields = Array.isArray(fieldsOrField) ? fieldsOrField : [fieldsOrField];
-      if (indexFields.length === 0) v.issue(`${path}.indexes.${index}`, "must not be empty");
-      for (const field of indexFields) {
-        if (typeof field !== "string" || (schemaValid && !fields.has(field))) {
-          v.issue(`${path}.indexes.${index}`, `'${String(field)}' must name a schema field`);
-        }
-      }
-    }
-  }
-
-  if (value.references !== undefined && v.record(value.references, `${path}.references`)) {
-    for (const [field, reference] of Object.entries(value.references)) {
-      if (schemaValid && !fields.has(field)) v.issue(`${path}.references.${field}`, "must name a schema field");
-      if (!v.record(reference, `${path}.references.${field}`)) continue;
-      v.nonEmptyString(reference.module, `${path}.references.${field}.module`);
-      v.nonEmptyString(reference.entity, `${path}.references.${field}.entity`);
-    }
-  }
-
-  if (value.retention !== undefined && v.record(value.retention, `${path}.retention`)) {
-    if (value.retention.ttlDays !== undefined) v.positiveInteger(value.retention.ttlDays, `${path}.retention.ttlDays`);
-    if (value.retention.ttlField !== undefined
-      && (!v.nonEmptyString(value.retention.ttlField, `${path}.retention.ttlField`)
-        || (schemaValid && !fields.has(value.retention.ttlField)))) {
-      if (typeof value.retention.ttlField === "string" && value.retention.ttlField.length > 0) {
-        v.issue(`${path}.retention.ttlField`, "must name a schema field");
-      }
-    }
-  }
-}
-
-function validateEvents(value: unknown, moduleId: string, v: Validator): void {
-  if (!v.record(value, "events")) return;
-  for (const [name, schema] of Object.entries(value)) {
-    if (!name.startsWith(`${moduleId}.`) || name.length === moduleId.length + 1) {
-      v.issue(`events.${name}`, `must begin with '${moduleId}.' and include an event name`);
-    }
-    v.schema(schema, `events.${name}`);
-  }
-}
-
-function validateOp(value: OpDecl, path: string, v: Validator): void {
-  if (!v.record(value, path)) return;
-  if (value.kind !== "query" && value.kind !== "mutation") v.issue(`${path}.kind`, "must be 'query' or 'mutation'");
-  v.schema(value.input, `${path}.input`);
-  v.schema(value.output, `${path}.output`);
-  v.grant(value.grant, `${path}.grant`);
-  if (value.advertiseScopes !== undefined) {
-    if (!Array.isArray(value.advertiseScopes) || value.advertiseScopes.length === 0) {
-      v.issue(`${path}.advertiseScopes`, "must be a non-empty array of grants when declared");
-    } else {
-      value.advertiseScopes.forEach((scope, index) => v.grant(scope, `${path}.advertiseScopes[${index}]`));
-    }
-  }
-  if (value.expose !== undefined) validateExpose(value.expose, `${path}.expose`, v);
-  v.nonEmptyString(value.summary, `${path}.summary`);
-  v.fn(value.handler, `${path}.handler`);
-  if (value.kind === "mutation" && typeof value.idempotent !== "boolean") {
-    v.issue(`${path}.idempotent`, "must be declared for mutations");
-  }
-  if (value.emits !== undefined && (!Array.isArray(value.emits) || value.emits.some((name) => typeof name !== "string"))) {
-    v.issue(`${path}.emits`, "must be an array of event names");
-  }
-  if (value.http !== undefined) {
-    if (!v.record(value.http, `${path}.http`)) return;
-    if (!["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"].includes(value.http.method)) {
-      v.issue(`${path}.http.method`, "is not a supported HTTP method");
-    }
-    if (v.nonEmptyString(value.http.path, `${path}.http.path`) && !value.http.path.startsWith("/")) {
-      v.issue(`${path}.http.path`, "must begin with '/'");
-    }
-  }
-}
-
-/**
- * Strictly validate an op's `expose` block. Each transport flag (`http`/`mcp`/`cli`) is OPTIONAL, but
- * when present MUST be a real boolean, and NO unknown key is tolerated. This is a fail-closed guard:
- * the transport-exclusion gates read `expose.mcp !== false` / `expose.http === false` (see
- * {@link import("./mcp-transport").isMcpExposed} / {@link import("./http-transport").deriveHttpRoutes}),
- * so a truthy-but-non-boolean flag (`expose: { mcp: "false" }`) or a typo'd key (`expose: { mpc: false }`)
- * would silently leave a "hidden" op — e.g. a `*System` reconciler twin — EXPOSED on that transport.
- * Rejecting the malformed manifest at `defineModule` time makes that class of mistake unrepresentable.
- */
-function validateExpose(value: unknown, path: string, v: Validator): void {
-  if (!v.record(value, path)) return;
-  for (const [key, flag] of Object.entries(value)) {
-    if (!EXPOSE_TARGETS.has(key)) {
-      v.issue(`${path}.${key}`, "is not a known expose target (must be one of 'http', 'mcp', 'cli')");
-      continue;
-    }
-    if (typeof flag !== "boolean") v.issue(`${path}.${key}`, "must be a boolean");
-  }
-}
-
-/**
- * A path param token — `{name}` (OpenAPI) or `:name` (Hono) — carries no routing significance
- * beyond "a param goes here": Hono matches `/timers/{id}` and `/timers/{timerId}` as the exact same
- * structural route, binding whichever param name each op declared. Collapsing every param token to
- * a constant placeholder before comparing routes makes the collision key match Hono's own notion of
- * "same route", while literal (non-param) segments are preserved exactly.
- */
-const PARAM_TOKEN_PATTERN = /\{[^}]+\}/g;
-const HONO_PARAM_TOKEN_PATTERN = /:[A-Za-z_][A-Za-z0-9_]*/g;
-
-/** Normalize an OpenAPI- or Hono-style path to its structural shape, so two paths that Hono would
- * route identically (differing only in path-param names) normalize to the same string. */
-export function normalizeRoutePath(path: string): string {
-  return path.replace(PARAM_TOKEN_PATTERN, "{}").replace(HONO_PARAM_TOKEN_PATTERN, "{}");
-}
-
-/** The key two ops collide under: same method + same structural route. Shared with
- * {@link deriveHttpRoutes}'s defense-in-depth guard so both stay consistent — a manifest must never
- * pass validation here and then throw at derive, or vice versa. */
-export function httpRouteCollisionKey(method: string, path: string): string {
-  return `${method} ${normalizeRoutePath(path)}`;
-}
-
-/**
- * Two ops declaring the same `http` method+structural-route silently collide once derived: the
- * Hono router keeps the first-registered handler while the OpenAPI doc keeps the last, so the
- * route serves one op while the doc advertises the other. Catch that authoring error here so every
- * consumer of the manifest (not just the HTTP transport) is protected.
- */
-function validateHttpRouteCollisions(value: unknown, v: Validator): void {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) return;
-  const seenBy = new Map<string, string>();
-  for (const [opName, rawOp] of Object.entries(value as Record<string, unknown>)) {
-    if (typeof rawOp !== "object" || rawOp === null) continue;
-    const http = (rawOp as { http?: unknown }).http;
-    if (typeof http !== "object" || http === null) continue;
-    const { method, path } = http as { method?: unknown; path?: unknown };
-    if (typeof method !== "string" || typeof path !== "string") continue;
-    const key = httpRouteCollisionKey(method, path);
-    const collidesWith = seenBy.get(key);
-    if (collidesWith !== undefined) {
-      v.issue(`ops.${opName}.http`, `'${method} ${path}' collides with ops.${collidesWith}.http — two ops may not declare the same method+route (path params are matched by position, not name)`);
-    } else {
-      seenBy.set(key, opName);
-    }
-  }
-}
-
-function validateRoutes(value: unknown, v: Validator): void {
-  if (!Array.isArray(value)) return v.issue("routes", "must be an array");
-  for (const [index, route] of value.entries()) validateRoute(route as RawRouteDecl, `routes.${index}`, v);
-}
-
-function validateRoute(value: RawRouteDecl, path: string, v: Validator): void {
-  if (!v.record(value, path)) return;
-  v.nonEmptyString(value.path, `${path}.path`);
-  v.grant(value.grant, `${path}.grant`);
-  if ("streaming" in value) {
-    if (value.streaming === "sse") v.fn(value.subscribe, `${path}.subscribe`);
-    else if (value.streaming === "websocket") v.fn(value.accept, `${path}.accept`);
-    else v.issue(`${path}.streaming`, "must be 'sse' or 'websocket'");
-  } else {
-    if (v.nonEmptyString(value.method, `${path}.method`)
-      && !["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"].includes(value.method)) {
-      v.issue(`${path}.method`, "is not a supported HTTP method");
-    }
-    v.fn(value.handler, `${path}.handler`);
-  }
-}
-
-function validateWorkflow(value: WorkflowDecl, path: string, v: Validator): void {
-  if (!v.record(value, path)) return;
-  v.schema(value.input, `${path}.input`);
-  v.schema(value.state, `${path}.state`);
-  v.fn(value.init, `${path}.init`);
-  const startValid = v.nonEmptyString(value.start, `${path}.start`);
-  if (!v.record(value.steps, `${path}.steps`)) return;
-  if (Object.keys(value.steps).length === 0) v.issue(`${path}.steps`, "must declare at least one step");
-  if (startValid && !(value.start in value.steps)) v.issue(`${path}.start`, "must name a declared step");
-  for (const [name, step] of Object.entries(value.steps)) {
-    const stepPath = `${path}.steps.${name}`;
-    if (!v.record(step, stepPath)) continue;
-    v.fn(step.run, `${stepPath}.run`);
-    if (step.timeoutMs !== undefined) v.positiveInteger(step.timeoutMs, `${stepPath}.timeoutMs`);
-    if (step.retry !== undefined) validateRetry(step.retry, `${stepPath}.retry`, v);
-  }
-}
-
-function validateCommand(value: HostCommandDecl, path: string, v: Validator): void {
-  if (!v.record(value, path)) return;
-  v.schema(value.input, `${path}.input`);
-  v.schema(value.result, `${path}.result`);
-  if (value.target !== "host-agent" && value.target !== "runner") v.issue(`${path}.target`, "must be 'host-agent' or 'runner'");
-  v.grant(value.grant, `${path}.grant`);
-  v.fn(value.idempotencyKey, `${path}.idempotencyKey`);
-  v.positiveInteger(value.timeoutMs, `${path}.timeoutMs`);
-  if (value.retry !== undefined) validateRetry(value.retry, `${path}.retry`, v);
-  if (value.whenDegraded !== undefined && value.whenDegraded !== "queue" && value.whenDegraded !== "reject") {
-    v.issue(`${path}.whenDegraded`, "must be 'queue' or 'reject'");
-  }
-}
-
-function validateRetry(value: RetryPolicy, path: string, v: Validator): void {
-  if (!v.record(value, path)) return;
-  v.positiveInteger(value.maxAttempts, `${path}.maxAttempts`);
-  if (!v.record(value.backoff, `${path}.backoff`)) return;
-  if (value.backoff.kind === "fixed") v.positiveInteger(value.backoff.delayMs, `${path}.backoff.delayMs`);
-  else if (value.backoff.kind === "exponential") {
-    v.positiveInteger(value.backoff.initialMs, `${path}.backoff.initialMs`);
-    v.positiveInteger(value.backoff.maxMs, `${path}.backoff.maxMs`);
-  } else v.issue(`${path}.backoff.kind`, "must be 'fixed' or 'exponential'");
-}
-
-function validateHealth(value: unknown, path: string, v: Validator): void {
-  if (!v.record(value, path)) return;
-  if (!v.record(value.probes, `${path}.probes`)) return;
-  for (const [name, probe] of Object.entries(value.probes)) {
-    const probePath = `${path}.probes.${name}`;
-    if (!v.record(probe, probePath)) continue;
-    if (probe.intervalMs !== undefined) v.positiveInteger(probe.intervalMs, `${probePath}.intervalMs`);
-    if (probe.check !== undefined) v.fn(probe.check, `${probePath}.check`);
-    if (!Array.isArray(probe.degrades) || probe.degrades.length === 0) v.issue(`${probePath}.degrades`, "must name at least one capability");
-    else for (const capability of probe.degrades) v.nonEmptyString(capability, `${probePath}.degrades`);
-    if (probe.intervalMs === undefined && probe.check !== undefined) v.issue(probePath, "a pull check must declare intervalMs");
-    if (probe.intervalMs !== undefined && probe.check === undefined) v.issue(probePath, "intervalMs requires a check callback");
-  }
-}
-
-function validateSecrets(value: unknown, v: Validator): void {
-  if (!Array.isArray(value)) return v.issue("secrets", "must be an array");
-  const seen = new Set<string>();
-  for (const [index, secret] of value.entries()) {
-    if (!v.nonEmptyString(secret, `secrets.${index}`)) continue;
-    if (seen.has(secret)) v.issue(`secrets.${index}`, `duplicates '${secret}'`);
-    seen.add(secret);
-  }
-}
-
-function validateUi(value: unknown, path: string, v: Validator): void {
-  if (!v.record(value, path)) return;
-  if (value.nav !== undefined && v.record(value.nav, `${path}.nav`)) {
-    v.nonEmptyString(value.nav.section, `${path}.nav.section`);
-    v.nonEmptyString(value.nav.icon, `${path}.nav.icon`);
-  }
-  if (value.surfaces !== undefined && !Array.isArray(value.surfaces)) v.issue(`${path}.surfaces`, "must be an array");
-  if (value.custom !== undefined) v.fn(value.custom, `${path}.custom`);
-}
-
-function validateAgentContext(value: unknown, v: Validator): void {
-  if (!v.record(value, "agentContext")) return;
-  v.nonEmptyString(value.summary, "agentContext.summary");
-  if (value.examples !== undefined && !Array.isArray(value.examples)) v.issue("agentContext.examples", "must be an array");
-  if (value.caveats !== undefined && !Array.isArray(value.caveats)) v.issue("agentContext.caveats", "must be an array");
-}
-
-function validateMigrations(value: unknown, v: Validator): void {
-  if (!Array.isArray(value)) return v.issue("data", "must be an array");
-  const ids = new Set<string>();
-  for (const [index, migration] of value.entries()) {
-    const path = `data.${index}`;
-    if (!v.record(migration, path)) continue;
-    if (v.nonEmptyString(migration.id, `${path}.id`)) {
-      if (ids.has(migration.id)) v.issue(`${path}.id`, `duplicates '${migration.id}'`);
-      ids.add(migration.id);
-    }
-    v.fn(migration.run, `${path}.run`);
-  }
-}
-
-function validateEmittedEvents(value: Record<string, unknown>, v: Validator): void {
-  const ops = value.ops ?? {};
-  const events = value.events ?? {};
-  if (!v.record(ops, "ops") || !v.record(events, "events")) return;
-  const declared = new Set(Object.keys(events));
-  for (const [opName, rawOp] of Object.entries(ops)) {
-    if (!v.record(rawOp, `ops.${opName}`) || !Array.isArray(rawOp.emits)) continue;
-    for (const event of rawOp.emits as EventName[]) {
-      if (!declared.has(event)) v.issue(`ops.${opName}.emits`, `'${event}' is not declared in events`);
-    }
-  }
-}

package/node_modules/@humwick/kernel/mcp-transport.ts

@@ -1,109 +0,0 @@
-import { z } from "zod";
-import type { Grant, ModuleDefinition, OpDecl } from "./contract";
-
-/**
- * K1-6 — the MCP tool surface, *derived* from a `defineModule` manifest (the sibling of
- * {@link import("./http-transport").deriveHttpRoutes}).
- *
- * There is no hand-written per-op tool table. {@link deriveMcpTools} reads each op's manifest and
- * produces one {@link DerivedMcpTool} per op that is MCP-exposed; a live MCP dispatcher spreads the
- * result into its tool list and routes each tool through {@link import("./module-host").ModuleHost.invoke},
- * which owns authorization (default-deny), I/O validation, and the atomic commit. The derivation
- * itself makes NO authorization decision — it decides only what is VISIBLE / advertised.
- *
- * ── The `*System`-twin structural exclusion (K-C2 / O1) ─────────────────────────────────────────────
- * A non-exposed op is excluded here **structurally**, by reading its `expose.mcp` flag — NOT by
- * re-filtering a hand-maintained name list that could drift from the manifest. Any op declaring
- * `expose.mcp === false` (the `*System` reconciler twins) is absent from the derived set, so no MCP
- * tool is ever authored for it and there is no transport path to invoke it. This is the ONLY place the
- * exclusion lives: the invoker deliberately does NOT gate on `expose` (a reconciler still reaches the
- * twins through a direct `host.invoke`), so removing them from every transport derivation is what makes
- * them unreachable over MCP/HTTP/CLI while leaving the internal seam intact.
- */
-
-/** One MCP tool derived from an op — everything a dispatcher needs to advertise it in `tools/list`
- *  and route a call, and nothing more. The tool name and I/O schema come straight from the manifest;
- *  `requiredScopes` is the ADVERTISED requirement (see below), and `grant` is what the invoker
- *  actually gates on (the two differ only for an op that is stricter in-handler than its entry grant). */
-export interface DerivedMcpTool {
-  readonly opName: string;
-  readonly op: OpDecl;
-  /** The MCP tool name a dispatcher registers (default `<prefix>_<opName>`, prefix = the module id). */
-  readonly name: string;
-  /** The tool description shown in `tools/list` — the op's `summary`. */
-  readonly description: string;
-  /** The op's raw input schema; a dispatcher converts it to the JSON Schema `tools/list` expects. */
-  readonly input: z.ZodType;
-  /** The grant the INVOKER gates on (`ModuleHost.invoke`'s default-deny check). */
-  readonly grant: Grant;
-  /** The scopes ADVERTISED as this tool's requirement (`tools/list.requiredScopes`). Equals the op's
-   *  `advertiseScopes` when declared, else `[grant]`. Advertising the op's true requirement (rather
-   *  than a bare entry `grant` an admin-only handler would still 403) keeps the surface honest (O3);
-   *  it is defense-in-depth over the invoker's default-deny, never the sole gate. */
-  readonly requiredScopes: readonly Grant[];
-  readonly kind: "query" | "mutation";
-}
-
-/** Whether an op is exposed over MCP. Default-expose (mirrors the HTTP surface): an op is MCP-exposed
- *  unless it explicitly opts out with `expose.mcp === false`. This is the single discriminator the
- *  `*System`-twin exclusion (O1) turns on — assert against THIS, not a hand-kept name list. */
-export function isMcpExposed(op: OpDecl): boolean {
-  return op.expose?.mcp !== false;
-}
-
-/** The advertised requiredScopes for an op: its explicit `advertiseScopes`, else `[grant]` (O3). */
-export function advertisedScopesOf(op: OpDecl): readonly Grant[] {
-  return op.advertiseScopes ?? [op.grant];
-}
-
-/**
- * Project a derived tool's Zod input to the JSON Schema an MCP `tools/list` advertises. Lives in the
- * kernel (which owns the `zod` dependency) so a src-side MCP dispatcher can consume a plain
- * `Record<string, unknown>` without taking a direct `zod` dependency — the sibling of the way
- * `deriveHttpRoutes`/`createHttpApp` keep the OpenAPI generation kernel-internal. Purely a projection:
- * it makes no authorization decision and reads only the op's declared input shape.
- */
-export function toMcpInputJsonSchema(tool: DerivedMcpTool): Record<string, unknown> {
-  return z.toJSONSchema(tool.input) as Record<string, unknown>;
-}
-
-export interface McpDerivationOptions {
-  /** Overrides the tool-name derivation. Receives the op name; defaults to `<prefix>_<opName>`. */
-  readonly toolName?: (opName: string) => string;
-  /** The prefix the default tool-name derivation uses. Defaults to the module id. */
-  readonly prefix?: string;
-}
-
-/**
- * Derive the MCP tool list from a manifest: one {@link DerivedMcpTool} per op that is MCP-exposed
- * ({@link isMcpExposed}). Ops declaring `expose.mcp === false` (the `*System` twins) are excluded
- * structurally, so the derived set can never author a tool for a non-exposed op (O1 / K-C2). Guards
- * against two ops deriving the same tool name so a collision can never silently shadow a tool.
- */
-export function deriveMcpTools(module: ModuleDefinition, options: McpDerivationOptions = {}): DerivedMcpTool[] {
-  const prefix = options.prefix ?? module.id;
-  const nameOf = options.toolName ?? ((opName: string) => `${prefix}_${opName}`);
-  const tools: DerivedMcpTool[] = [];
-  const seen = new Map<string, string>();
-  for (const [opName, op] of Object.entries(module.ops ?? {})) {
-    // O1: a non-exposed op is unreachable over MCP because no tool is authored for it.
-    if (!isMcpExposed(op)) continue;
-    const name = nameOf(opName);
-    const collidesWith = seen.get(name);
-    if (collidesWith !== undefined) {
-      throw new Error(`duplicate MCP tool name '${name}': derived from both '${collidesWith}' and '${opName}'`);
-    }
-    seen.set(name, opName);
-    tools.push({
-      opName,
-      op,
-      name,
-      description: op.summary,
-      input: op.input as z.ZodType,
-      grant: op.grant,
-      requiredScopes: advertisedScopesOf(op),
-      kind: op.kind,
-    });
-  }
-  return tools;
-}