@spfn/core 0.3.0-beta.2 → 0.3.0-beta.21

package/dist/ops/index.js

@@ -7,6 +7,8 @@ var RouteBuilder = class _RouteBuilder {
   _middlewares;
   _skipMiddlewares;
   _contract;
+  _effect;
+  _summary;
   /**
    * Create a new RouteBuilder with copied properties and optional overrides
    */
@@ -19,6 +21,8 @@ var RouteBuilder = class _RouteBuilder {
     builder._middlewares = overrides?.middlewares ?? this._middlewares;
     builder._skipMiddlewares = overrides?.skipMiddlewares ?? this._skipMiddlewares;
     builder._contract = overrides?.contract ?? this._contract;
+    builder._effect = overrides?.effect ?? this._effect;
+    builder._summary = overrides?.summary ?? this._summary;
     return builder;
   }
   /**
@@ -138,7 +142,7 @@ var RouteBuilder = class _RouteBuilder {
    * @example
    * ```ts
    * // Skip specific middlewares
-   * route.get('/health')
+   * route.get('/status')
    *   .skip(['auth', 'rateLimit'])
    *   .handler(async (c) => c.json({ status: 'ok' }));
    *
@@ -189,6 +193,49 @@ var RouteBuilder = class _RouteBuilder {
   contract(contract) {
     return this.clone({ contract });
   }
+  /**
+   * Declare what invoking this route does
+   *
+   * Read by a command surface (`@spfn/core/surface`, `@spfn/core/ops`),
+   * which announces it in its manifest so a machine caller can tell a read
+   * from a write before it calls — `spfn ops call` asks for `--yes` before a
+   * `destructive` command. A surface built with `defineSurface` refuses an
+   * app command that does not declare one; on `/_ops` it is optional.
+   *
+   * Nothing else reads it: codegen, the route map, and the contract are
+   * unaffected, and a route outside any surface simply carries it.
+   *
+   * @example
+   * ```ts
+   * export const pageAdd = app.route.post('/pages')
+   *   .input({ body: PageAddBody })
+   *   .effect('write')
+   *   .summary('Add a page to the blueprint')
+   *   .handler(async (c) => { ... });
+   * ```
+   */
+  effect(effect) {
+    return this.clone({ effect });
+  }
+  /**
+   * Describe this route in one line for a command surface's manifest
+   *
+   * A surface announces it beside the command in `spfn ops list` and
+   * `--describe`, and refuses one that is empty or longer than 500
+   * characters. Codegen, the route map, and the contract ignore it. On a
+   * module command the module's own summary wins.
+   *
+   * @example
+   * ```ts
+   * export const pageAdd = app.route.post('/pages')
+   *   .effect('write')
+   *   .summary('Add a page to the blueprint')
+   *   .handler(async (c) => { ... });
+   * ```
+   */
+  summary(summary) {
+    return this.clone({ summary });
+  }
   /**
    * Define handler function
    *
@@ -244,6 +291,8 @@ var RouteBuilder = class _RouteBuilder {
       middlewares: this._middlewares,
       skipMiddlewares: this._skipMiddlewares,
       contract: this._contract,
+      ...this._effect !== void 0 ? { effect: this._effect } : {},
+      ...this._summary !== void 0 ? { summary: this._summary } : {},
       handler: fn,
       _input: {},
       _interceptor: {},
@@ -268,43 +317,33 @@ var route = {
 };
 
 // src/route/router.ts
-function createRouterInstance(routes, packageRouters = [], globalMiddlewares = [], contractVersion = null) {
+function createRouterInstance(state) {
   return {
-    routes,
-    _routes: routes,
-    _packageRouters: packageRouters,
-    _globalMiddlewares: globalMiddlewares,
-    _contractVersion: contractVersion,
+    routes: state.routes,
+    _routes: state.routes,
+    _packageRouters: state.packageRouters,
+    _globalMiddlewares: state.globalMiddlewares,
+    _contractVersion: state.contractVersion,
+    _publishesRouteMap: state.publishesRouteMap,
     packages(routers) {
-      const newPackageRouters = [...this._packageRouters, ...routers];
+      const newPackageRouters = [...state.packageRouters, ...routers];
       for (const pkgRouter of routers) {
         if (pkgRouter._packageRouters?.length > 0) {
           newPackageRouters.push(...pkgRouter._packageRouters);
         }
       }
-      return createRouterInstance(
-        this.routes,
-        newPackageRouters,
-        this._globalMiddlewares,
-        this._contractVersion
-      );
+      assertDistinctSurfaces(newPackageRouters);
+      return createRouterInstance({ ...state, packageRouters: newPackageRouters });
     },
     use(middlewares) {
-      return createRouterInstance(
-        this.routes,
-        this._packageRouters,
-        [...this._globalMiddlewares, ...middlewares],
-        this._contractVersion
-      );
+      return createRouterInstance({
+        ...state,
+        globalMiddlewares: [...state.globalMiddlewares, ...middlewares]
+      });
     },
     contractVersion(version) {
       assertContractVersion(version);
-      return createRouterInstance(
-        this.routes,
-        this._packageRouters,
-        this._globalMiddlewares,
-        version
-      );
+      return createRouterInstance({ ...state, contractVersion: version });
     }
   };
 }
@@ -315,17 +354,50 @@ function assertContractVersion(version) {
     );
   }
 }
-function defineRouter(routes) {
-  return createRouterInstance(routes);
+function assertDistinctSurfaces(packageRouters) {
+  const namespaces = /* @__PURE__ */ new Set();
+  for (const router of packageRouters) {
+    const namespace = router._surfaceNamespace;
+    if (namespace === void 0) {
+      continue;
+    }
+    if (namespaces.has(namespace)) {
+      throw new Error(
+        `.packages() mounts two command surfaces on "${namespace}". Both serve ${namespace}/_manifest, so the second one's commands would answer while no manifest lists them. Mount one router per namespace.`
+      );
+    }
+    namespaces.add(namespace);
+  }
+}
+function defineUnmappedRouter(routes) {
+  return createRouterInstance({
+    routes,
+    packageRouters: [],
+    globalMiddlewares: [],
+    contractVersion: null,
+    publishesRouteMap: false
+  });
 }
 
-// src/ops/manifest.ts
-var OpsRouterError = class extends Error {
+// src/surface/error.ts
+var SurfaceError = class extends Error {
   constructor(message) {
     super(message);
-    this.name = "OpsRouterError";
+    this.name = "SurfaceError";
   }
 };
+
+// src/surface/wording.ts
+var SURFACE_WORDING = {
+  noun: "surface",
+  builder: "`<surface>.route`",
+  factory: "defineSurface"
+};
+function capitalized(noun) {
+  return noun.charAt(0).toUpperCase() + noun.slice(1);
+}
+
+// src/surface/manifest.ts
 function isRouter(value) {
   return value !== null && typeof value === "object" && "routes" in value && "_routes" in value;
 }
@@ -349,152 +421,621 @@ function toCommandInput(input) {
   }
   return sections;
 }
-function collectOpsCommands(routes) {
+function collectSurfaceCommands(routes, wording = SURFACE_WORDING) {
   const commands = [];
-  visit(routes, commands, /* @__PURE__ */ new Map());
+  visit(routes, commands, /* @__PURE__ */ new Map(), wording);
   commands.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
   return commands;
 }
-function visit(routes, commands, claimed) {
+function visit(routes, commands, claimed, wording) {
   for (const [name, entry] of Object.entries(routes)) {
     if (isRouter(entry)) {
-      visit(entry.routes, commands, claimed);
+      visit(entry.routes, commands, claimed, wording);
       continue;
     }
     if (!isRouteDef(entry) || !entry.method || !entry.path) {
       continue;
     }
-    assertUnclaimedName(name, entry.path, claimed);
+    assertUnclaimedName(name, entry.path, claimed, wording);
     commands.push({
       name,
       method: entry.method,
       path: entry.path,
+      ...entry.summary !== void 0 ? { summary: entry.summary } : {},
+      ...entry.effect !== void 0 ? { effect: entry.effect } : {},
       input: toCommandInput(entry.input)
     });
   }
 }
-function assertUnclaimedName(name, path, claimed) {
+function assertUnclaimedName(name, path, claimed, wording) {
   const existing = claimed.get(name);
   if (existing !== void 0) {
-    throw new OpsRouterError(
-      `Two ops routes are named "${name}" ("${existing}" and "${path}"). Command names are flattened across nested routers, so each must be unique for the CLI to resolve the one an operator asked for.`
+    throw new SurfaceError(
+      `Two ${wording.noun} routes are named "${name}" ("${existing}" and "${path}"). Command names are flattened across nested routers, so each must be unique for a client to resolve the one its caller asked for.`
     );
   }
   claimed.set(name, path);
 }
 
-// src/ops/create-ops-router.ts
-var OPS_PATH_PREFIX = "/_ops/";
-var OPS_MANIFEST_PATH = "/_ops/_manifest";
-var OPS_MANIFEST_NAME = "getOpsManifest";
+// src/surface/route-overlap.ts
+function routeSegments(path) {
+  return path.split("/").slice(1).map((raw) => {
+    if (raw === "*" || raw.endsWith("*")) {
+      return { kind: "wildcard", value: raw, optional: true };
+    }
+    if (raw.startsWith(":")) {
+      return {
+        kind: "parameter",
+        value: raw.slice(1).replace(/\?$/, ""),
+        optional: raw.endsWith("?")
+      };
+    }
+    return { kind: "static", value: raw, optional: false };
+  });
+}
+function customPattern(parameter) {
+  const openingBrace = parameter.indexOf("{");
+  return openingBrace >= 0 && parameter.endsWith("}") ? parameter.slice(openingBrace + 1, -1) : null;
+}
+function parameterAccepts(parameter, value) {
+  const pattern = customPattern(parameter);
+  if (pattern === null) {
+    return value.length > 0 && !value.includes("/");
+  }
+  try {
+    return new RegExp(`^(?:${pattern})$`).test(value);
+  } catch {
+    return true;
+  }
+}
+function remainingStaticPath(segments, from) {
+  const remaining = segments.slice(from);
+  return remaining.every((segment) => segment.kind === "static") ? remaining.map((segment) => segment.value).join("/") : null;
+}
+function routePatternsOverlap(firstPath, secondPath) {
+  const first = routeSegments(firstPath);
+  const second = routeSegments(secondPath);
+  const length = Math.max(first.length, second.length);
+  for (let index = 0; index < length; index++) {
+    const left = first[index];
+    const right = second[index];
+    if (!left || !right) {
+      const remaining = left ? first.slice(index) : second.slice(index);
+      return remaining.every((segment) => segment.optional || segment.kind === "wildcard");
+    }
+    if (left.kind === "wildcard" || right.kind === "wildcard") {
+      return true;
+    }
+    if (left.kind === "static" && right.kind === "static") {
+      if (left.value !== right.value) {
+        return false;
+      }
+      continue;
+    }
+    if (left.kind === "parameter" && right.kind === "static") {
+      const remaining = remainingStaticPath(second, index);
+      if (customPattern(left.value) !== null && remaining !== null && parameterAccepts(left.value, remaining)) {
+        return true;
+      }
+      if (!parameterAccepts(left.value, right.value)) {
+        return customPattern(left.value) !== null && remaining === null;
+      }
+      if (customPattern(left.value) !== null && first.length !== second.length) {
+        return true;
+      }
+      continue;
+    }
+    if (left.kind === "static" && right.kind === "parameter") {
+      const remaining = remainingStaticPath(first, index);
+      if (customPattern(right.value) !== null && remaining !== null && parameterAccepts(right.value, remaining)) {
+        return true;
+      }
+      if (!parameterAccepts(right.value, left.value)) {
+        return customPattern(right.value) !== null && remaining === null;
+      }
+      if (customPattern(right.value) !== null && first.length !== second.length) {
+        return true;
+      }
+      continue;
+    }
+    return true;
+  }
+  return true;
+}
+
+// src/surface/module.ts
+var MODULE_ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+var COMMAND_NAME = /^[A-Za-z][A-Za-z0-9]*(?:\.[A-Za-z][A-Za-z0-9]*)*$/;
+var CONTRACT_VERSION = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)*$/;
+var EFFECTS = /* @__PURE__ */ new Set(["read", "write", "destructive"]);
+var PATH_BASE = "https://spfn.invalid";
+function isSurfaceEffect(value) {
+  return EFFECTS.has(value);
+}
+function assertText(label, value) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new SurfaceError(`${label} must be a non-empty string.`);
+  }
+}
+function assertStableModulePath(at, moduleId, commandName, path) {
+  const label = `${at.label} command "${moduleId}.${commandName}" path "${path}"`;
+  const transportPath = path.replace(/[{}?#]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+  let url;
+  try {
+    url = new URL(transportPath, PATH_BASE);
+  } catch {
+    throw new SurfaceError(`${label} is not a valid URL path.`);
+  }
+  if (url.origin !== PATH_BASE || url.search !== "" || url.hash !== "" || url.pathname !== transportPath) {
+    throw new SurfaceError(`${label} is not a stable plain absolute path.`);
+  }
+  const slashCount = (path.match(/\//g) ?? []).length;
+  let decoded = path;
+  for (let depth = 0; depth < 8; depth++) {
+    let next;
+    try {
+      next = decodeURIComponent(decoded);
+    } catch {
+      throw new SurfaceError(`${label} contains malformed percent encoding.`);
+    }
+    if (next.includes("\\") || (next.match(/\//g) ?? []).length !== slashCount || next.split("/").some((segment) => segment === "." || segment === "..")) {
+      throw new SurfaceError(`${label} contains encoded path separators or dot segments.`);
+    }
+    if (next === decoded) {
+      return;
+    }
+    decoded = next;
+  }
+  throw new SurfaceError(`${label} uses too many percent-encoding layers.`);
+}
+function assertCliCallableModulePath(at, moduleId, commandName, path) {
+  const unsupported = path.split("/").slice(1).find((segment) => segment === "*" || segment.includes("*") || (segment.startsWith(":") ? !/^:[A-Za-z0-9_]+$/.test(segment) : !/^[A-Za-z0-9._~-]+$/.test(segment)));
+  if (unsupported !== void 0) {
+    throw new SurfaceError(
+      `${at.label} command "${moduleId}.${commandName}" path segment "${unsupported}" is not CLI-callable. Module routes support URL-safe static segments and simple :name parameters only; optional, wildcard, and custom-regex parameters are not supported.`
+    );
+  }
+}
+function assertCommand(at, moduleId, name, command) {
+  if (!COMMAND_NAME.test(name)) {
+    throw new SurfaceError(
+      `${at.label} module "${moduleId}" has invalid command name "${name}". Use dot-separated alphanumeric names.`
+    );
+  }
+  assertText(`${at.label} command "${moduleId}.${name}" summary`, command?.summary);
+  if (!EFFECTS.has(command?.effect)) {
+    throw new SurfaceError(
+      `${at.label} command "${moduleId}.${name}" has invalid effect ${JSON.stringify(command?.effect)}.`
+    );
+  }
+  if (!Array.isArray(command?.scopes) || command.scopes.length === 0 || command.scopes.some((scope) => typeof scope !== "string" || scope.trim().length === 0)) {
+    throw new SurfaceError(`${at.label} command "${moduleId}.${name}" must declare at least one non-empty scope.`);
+  }
+  const route2 = command?.route;
+  if (!route2 || typeof route2.handler !== "function" || !route2.method || !route2.path) {
+    throw new SurfaceError(`${at.label} command "${moduleId}.${name}" must carry a complete route.`);
+  }
+  assertStableModulePath(at, moduleId, name, route2.path);
+  assertCliCallableModulePath(at, moduleId, name, route2.path);
+  const modulePath = `${at.namespace}/${moduleId}/`;
+  if (!route2.path.startsWith(modulePath)) {
+    throw new SurfaceError(
+      `${at.label} command "${moduleId}.${name}" is at "${route2.path}", outside "${modulePath}". A module mounted on "${at.namespace}" keeps every command under "${modulePath}".`
+    );
+  }
+  if (route2.path.split("/").includes("..")) {
+    throw new SurfaceError(`${at.label} command "${moduleId}.${name}" path climbs out of its module namespace.`);
+  }
+}
+function validateSurfaceModule(module, namespace, wording = SURFACE_WORDING) {
+  const at = { namespace, label: capitalized(wording.noun) };
+  if (!MODULE_ID.test(module?.id ?? "")) {
+    throw new SurfaceError(
+      `${at.label} module id ${JSON.stringify(module?.id)} is invalid. Use lower-kebab-case.`
+    );
+  }
+  assertText(`${at.label} module "${module.id}" source`, module.source);
+  assertText(`${at.label} module "${module.id}" summary`, module.summary);
+  if (!CONTRACT_VERSION.test(module.contractVersion)) {
+    throw new SurfaceError(
+      `${at.label} module "${module.id}" contractVersion must be a semantic version.`
+    );
+  }
+  if (!module.commands || typeof module.commands !== "object" || Array.isArray(module.commands)) {
+    throw new SurfaceError(`${at.label} module "${module.id}" commands must be an object.`);
+  }
+  const signatures = /* @__PURE__ */ new Map();
+  const claimedRoutes = [];
+  for (const [name, command] of Object.entries(module.commands)) {
+    assertCommand(at, module.id, name, command);
+    const signature = `${command.route.method} ${command.route.path}`;
+    const existing = signatures.get(signature);
+    if (existing) {
+      throw new SurfaceError(
+        `${at.label} module "${module.id}" commands "${existing}" and "${name}" both use ${signature}.`
+      );
+    }
+    signatures.set(signature, name);
+    const overlapping = claimedRoutes.find((claim) => claim.method === command.route.method && routePatternsOverlap(claim.path, command.route.path));
+    if (overlapping) {
+      throw new SurfaceError(
+        `${at.label} module "${module.id}" commands "${overlapping.name}" and "${name}" have overlapping ${command.route.method} routes ("${overlapping.path}" and "${command.route.path}").`
+      );
+    }
+    claimedRoutes.push({
+      name,
+      method: command.route.method,
+      path: command.route.path
+    });
+  }
+  return module;
+}
+
+// src/surface/namespace.ts
+var NAMESPACE = /^(?:\/[A-Za-z0-9_-]+)+$/;
+function assertNamespace(namespace) {
+  if (typeof namespace !== "string" || !NAMESPACE.test(namespace)) {
+    throw new SurfaceError(
+      `Surface namespace ${JSON.stringify(namespace)} is invalid. Use an absolute path of [A-Za-z0-9_-] segments without a trailing slash, such as "/_app".`
+    );
+  }
+}
+function manifestPathOf(namespace) {
+  return `${namespace}/_manifest`;
+}
+function manifestNameOf(namespace) {
+  return `get${namespace.slice(1).replace(/_[a-z]|[A-Z_/-]/g, encodedCharacter)}Manifest`;
+}
+var ESCAPES = { "_": "_", "-": "d", "/": "s" };
+function encodedCharacter(match) {
+  if (match.length === 2) {
+    return match.charAt(1).toUpperCase();
+  }
+  return `_${ESCAPES[match] ?? match}`;
+}
+function toSurfacePath(namespace, path, wording) {
+  const label = capitalized(wording.noun);
+  if (!path.startsWith("/")) {
+    throw new SurfaceError(
+      `${label} route path "${path}" must start with "/". It is appended to "${namespace}", so "${path}" would read as "${namespace}${path}".`
+    );
+  }
+  if (path === "/") {
+    throw new SurfaceError(
+      `${label} route path "/" names no command \u2014 "${namespace}" itself is not a command.`
+    );
+  }
+  return namespace + path;
+}
+function surfaceRouteBuilder(namespace, wording) {
+  const method = (name) => (path) => route[name](toSurfacePath(namespace, path, wording));
+  return {
+    get: method("get"),
+    post: method("post"),
+    put: method("put"),
+    patch: method("patch"),
+    delete: method("delete")
+  };
+}
+
+// src/surface/define-surface.ts
+var MAX_COMMAND_SUMMARY_LENGTH = 500;
+var EFFECT_METHOD = ".effect('read' | 'write' | 'destructive')";
 function isRouter2(value) {
   return value !== null && typeof value === "object" && "routes" in value && "_routes" in value;
 }
 function isRouteDef2(value) {
   return value !== null && typeof value === "object" && "handler" in value;
 }
-function assertOpsRoute(name, def) {
+function assertSurfaceRoute(plan, name, def) {
+  const label = capitalized(plan.wording.noun);
   if (!def.method || !def.path) {
-    throw new OpsRouterError(
-      `Ops route "${name}" has no method or path. An ops command is invoked on the wire, so both are required.`
+    throw new SurfaceError(
+      `${label} route "${name}" has no method or path. A command is invoked on the wire, so both are required.`
+    );
+  }
+  if (!def.path.startsWith(plan.prefix)) {
+    throw new SurfaceError(
+      `${label} route "${name}" is at "${def.path}", outside "${plan.prefix}". Build ${plan.wording.noun} routes with ${plan.wording.builder} rather than \`route\` \u2014 it applies the namespace, so the path a definition carries is only the part the app owns.`
+    );
+  }
+  if (def.path === plan.manifestPath) {
+    throw new SurfaceError(
+      `${label} route "${name}" claims "${plan.manifestPath}", which is reserved for the manifest. The manifest is registered first, so this route would never answer.`
+    );
+  }
+}
+function assertCommandMetadata(plan, name, def) {
+  const label = `${capitalized(plan.wording.noun)} command "${name}"`;
+  if (def.effect === void 0 && plan.requireEffect) {
+    throw new SurfaceError(
+      `${label} declares no effect. A client reads it to decide whether to call, retry, or ask for confirmation, so ${plan.wording.factory} refuses a command without one. Declare it on the route with ${EFFECT_METHOD}.`
+    );
+  }
+  if (def.effect !== void 0 && !isSurfaceEffect(def.effect)) {
+    throw new SurfaceError(
+      `${label} has invalid effect ${JSON.stringify(def.effect)}. A client knows no other, so declare it with ${EFFECT_METHOD}.`
+    );
+  }
+  assertCommandSummary(label, def.summary);
+}
+function assertCommandSummary(label, summary) {
+  if (summary === void 0) {
+    return;
+  }
+  if (typeof summary !== "string" || summary.trim().length === 0) {
+    throw new SurfaceError(
+      `${label} has an empty summary. A client would list it as a command described by nothing; give .summary() one line of text, or leave it out.`
     );
   }
-  if (!def.path.startsWith(OPS_PATH_PREFIX)) {
-    throw new OpsRouterError(
-      `Ops route "${name}" is at "${def.path}", outside "${OPS_PATH_PREFIX}". Build ops routes with \`opsRoute\` rather than \`route\` \u2014 it applies the namespace, so the path a definition carries is only the part the app owns.`
+  if (summary.length > MAX_COMMAND_SUMMARY_LENGTH) {
+    throw new SurfaceError(
+      `${label} has a summary of ${summary.length} characters, over the ${MAX_COMMAND_SUMMARY_LENGTH} a client accepts \u2014 it would drop the command's metadata and treat it as destructive. Shorten it.`
     );
   }
-  if (def.path === OPS_MANIFEST_PATH) {
-    throw new OpsRouterError(
-      `Ops route "${name}" claims "${OPS_MANIFEST_PATH}", which is reserved for the manifest. The manifest is registered first, so this route would never answer.`
+}
+function assertModuleRouteEffect(plan, name, definition) {
+  const routeEffect = definition.route.effect;
+  if (routeEffect !== void 0 && routeEffect !== definition.effect) {
+    throw new SurfaceError(
+      `${capitalized(plan.wording.noun)} command "${name}" is declared ${JSON.stringify(definition.effect)} by its module, but its route says .effect(${JSON.stringify(routeEffect)}). The manifest announces the module's declaration, so the two cannot disagree. Drop the route's .effect() or make it match.`
     );
   }
 }
-function assertOpsName(name) {
-  if (name === OPS_MANIFEST_NAME) {
-    throw new OpsRouterError(
-      `Ops route name "${OPS_MANIFEST_NAME}" is reserved for the manifest route.`
+function assertSurfaceName(plan, name) {
+  if (name === plan.manifestName) {
+    throw new SurfaceError(
+      `${capitalized(plan.wording.noun)} route name "${plan.manifestName}" is reserved for the manifest route.`
     );
   }
 }
-function rebuildNestedRouter(name, router, auth, inherited) {
+function rebuildNestedRouter(plan, name, router, commandsByName, inherited) {
   if (router._packageRouters?.length > 0) {
-    throw new OpsRouterError(
-      `Ops router "${name}" mounts package routers with .packages(). Their routes bypass the prefix check and the auth injection, so an ops surface cannot carry them.`
+    throw new SurfaceError(
+      `${capitalized(plan.wording.noun)} router "${name}" mounts package routers with .packages(). Their routes bypass the prefix check and the auth injection, so a surface cannot carry them.`
     );
   }
   const handedDown = [...inherited, ...router._globalMiddlewares ?? []];
-  let rebuilt = defineRouter(
-    secureRoutes(router.routes, auth, handedDown)
+  let rebuilt = defineUnmappedRouter(
+    secureRoutes(plan, router.routes, commandsByName, handedDown)
   );
   if (router._contractVersion) {
     rebuilt = rebuilt.contractVersion(router._contractVersion);
   }
   return rebuilt;
 }
-function secureRoutes(routes, auth, inherited = []) {
+function secureRoutes(plan, routes, commandsByName, inherited = []) {
   const secured = {};
   for (const [name, entry] of Object.entries(routes)) {
-    assertOpsName(name);
+    assertSurfaceName(plan, name);
     if (isRouter2(entry)) {
-      secured[name] = rebuildNestedRouter(name, entry, auth, inherited);
+      secured[name] = rebuildNestedRouter(plan, name, entry, commandsByName, inherited);
       continue;
     }
     if (!isRouteDef2(entry)) {
-      throw new OpsRouterError(`Ops router entry "${name}" is neither a route nor a router.`);
+      throw new SurfaceError(
+        `${capitalized(plan.wording.noun)} router entry "${name}" is neither a route nor a router.`
+      );
     }
-    assertOpsRoute(name, entry);
+    assertSurfaceRoute(plan, name, entry);
+    assertCommandMetadata(plan, name, entry);
+    const guard = plan.authorize?.(commandsByName.get(name));
     secured[name] = {
       ...entry,
-      middlewares: [auth, ...inherited, ...entry.middlewares ?? []]
+      middlewares: commandChain(plan, name, guard, [...inherited, ...entry.middlewares ?? []])
     };
   }
   return secured;
 }
-function createOpsRouter(routes, options) {
-  if (!options?.auth) {
-    throw new OpsRouterError(
-      "createOpsRouter requires an auth middleware ({ auth: ... }). An ops surface reachable without authentication cannot be created."
+function commandChain(plan, name, guard, declared) {
+  if (guard === void 0) {
+    return [plan.auth, ...declared];
+  }
+  const guardName = middlewareNameOf(guard);
+  if (guardName !== void 0) {
+    refuseGuardCollision(plan, name, guardName, declared);
+  }
+  return [plan.auth, guard, ...declared];
+}
+function refuseGuardCollision(plan, name, guardName, declared) {
+  const noun = capitalized(plan.wording.noun);
+  if (middlewareNameOf(plan.auth) === guardName) {
+    throw new SurfaceError(
+      `${noun} command "${name}"'s guard shares the name "${guardName}" with the surface's auth middleware. Route registration keeps one middleware per name, so the command's guard would never run. Give one of the two a distinct name.`
+    );
+  }
+  if (declared.some((middleware) => middlewareNameOf(middleware) === guardName)) {
+    throw new SurfaceError(
+      `${noun} command "${name}" declares a middleware named "${guardName}", the name of the guard authorize gave it. Route registration keeps one middleware per name, so the command's own guard would never run. Give one of the two a distinct name.`
+    );
+  }
+}
+function middlewareNameOf(middleware) {
+  return typeof middleware === "function" ? void 0 : middleware.name;
+}
+function assertModuleCommandFree(plan, command, appCommands, claimed) {
+  const noun = plan.wording.noun;
+  if (claimed.names.has(command.name)) {
+    throw new SurfaceError(`Two ${noun} commands are named "${command.name}".`);
+  }
+  const signature = `${command.method} ${command.path}`;
+  const existing = claimed.signatures.get(signature);
+  if (existing) {
+    throw new SurfaceError(
+      `${capitalized(noun)} commands "${existing}" and "${command.name}" both use ${signature}.`
     );
   }
+  const overlapping = appCommands.find((app) => app.method === command.method && routePatternsOverlap(app.path, command.path));
+  if (overlapping) {
+    throw new SurfaceError(
+      `App ${noun} command "${overlapping.name}" at ${command.method} ${overlapping.path} overlaps module command "${command.name}" at ${command.method} ${command.path}. Which one answers cannot depend on route registration order.`
+    );
+  }
+  claimed.names.add(command.name);
+  claimed.signatures.set(signature, command.name);
+}
+function compileModules(plan, appCommands) {
+  const compiled = { descriptors: [], commands: [], routes: {} };
+  const moduleIds = /* @__PURE__ */ new Set();
+  const claimed = {
+    names: new Set(appCommands.map((command) => command.name)),
+    signatures: new Map(appCommands.map((command) => [`${command.method} ${command.path}`, command.name]))
+  };
+  for (const rawModule of plan.modules) {
+    const module = validateSurfaceModule(rawModule, plan.namespace, plan.wording);
+    if (moduleIds.has(module.id)) {
+      throw new SurfaceError(`Two ${plan.wording.noun} modules use id "${module.id}".`);
+    }
+    moduleIds.add(module.id);
+    compiled.descriptors.push({
+      id: module.id,
+      source: module.source,
+      contractVersion: module.contractVersion,
+      summary: module.summary
+    });
+    for (const [localName, definition] of Object.entries(module.commands)) {
+      const command = {
+        name: `${module.id}.${localName}`,
+        module: module.id,
+        summary: definition.summary,
+        effect: definition.effect,
+        scopes: [...definition.scopes],
+        method: definition.route.method,
+        path: definition.route.path,
+        input: collectSurfaceCommands({ [localName]: definition.route }, plan.wording)[0].input
+      };
+      assertModuleRouteEffect(plan, command.name, definition);
+      assertModuleCommandFree(plan, command, appCommands, claimed);
+      compiled.commands.push(command);
+      compiled.routes[command.name] = { route: definition.route, command };
+    }
+  }
+  compiled.descriptors.sort((a, b) => a.id.localeCompare(b.id));
+  compiled.commands.sort((a, b) => a.name.localeCompare(b.name));
+  return compiled;
+}
+function secureModuleRoutes(plan, routes) {
+  const secured = {};
+  for (const [name, definition] of Object.entries(routes)) {
+    assertSurfaceName(plan, name);
+    assertSurfaceRoute(plan, name, definition.route);
+    secured[name] = {
+      ...definition.route,
+      middlewares: commandChain(
+        plan,
+        name,
+        plan.authorize?.(definition.command),
+        definition.route.middlewares ?? []
+      )
+    };
+  }
+  return secured;
+}
+function manifestRoute(plan, manifest) {
+  const builder = route.get(plan.manifestPath);
+  return (plan.manifest === "public" ? builder.skip(["auth"]) : builder.use([plan.auth])).handler(async () => manifest);
+}
+function buildRouter(plan, routes) {
+  const appCommands = collectSurfaceCommands(routes, plan.wording);
+  const moduleSurface = compileModules(plan, appCommands);
+  const commands = [...appCommands, ...moduleSurface.commands].sort((a, b) => a.name.localeCompare(b.name));
   const manifest = {
     manifestVersion: 1,
-    commands: collectOpsCommands(routes)
+    ...moduleSurface.descriptors.length > 0 ? { modules: moduleSurface.descriptors } : {},
+    commands
+  };
+  const commandsByName = new Map(appCommands.map((command) => [command.name, command]));
+  const secured = secureRoutes(plan, routes, commandsByName);
+  const securedModules = secureModuleRoutes(plan, moduleSurface.routes);
+  return Object.defineProperty(defineUnmappedRouter({
+    [plan.manifestName]: manifestRoute(plan, manifest),
+    ...secured,
+    ...securedModules
+  }), "_surfaceNamespace", { value: plan.namespace, enumerable: false });
+}
+function planOf(options, wording, rules) {
+  assertNamespace(options?.namespace);
+  if (!options.auth) {
+    throw new SurfaceError(
+      `${wording.factory} requires an auth middleware ({ auth: ... }). A surface reachable without authentication cannot be created.`
+    );
+  }
+  const modules = options.modules ?? [];
+  if (modules.length > 0 && !options.authorize) {
+    throw new SurfaceError(`${wording.factory} requires an authorize function when modules are mounted.`);
+  }
+  const manifest = options.manifest ?? "authenticated";
+  if (manifest !== "authenticated" && manifest !== "public") {
+    throw new SurfaceError(
+      `${wording.factory} manifest must be 'authenticated' or 'public', got ${JSON.stringify(manifest)}.`
+    );
+  }
+  return {
+    namespace: options.namespace,
+    prefix: `${options.namespace}/`,
+    manifestPath: manifestPathOf(options.namespace),
+    manifestName: manifestNameOf(options.namespace),
+    auth: options.auth,
+    authorize: options.authorize,
+    manifest,
+    modules,
+    wording,
+    requireEffect: rules.requireEffect
+  };
+}
+function createSurface(options, wording, rules) {
+  const plan = planOf(options, wording, rules);
+  return {
+    namespace: plan.namespace,
+    route: surfaceRouteBuilder(plan.namespace, wording),
+    router: (routes) => buildRouter(plan, routes)
   };
-  const secured = secureRoutes(routes, options.auth);
-  const manifestRoute = route.get(OPS_MANIFEST_PATH).use([options.auth]).handler(async () => manifest);
-  return defineRouter({
-    [OPS_MANIFEST_NAME]: manifestRoute,
-    ...secured
-  });
 }
 
+// src/ops/wording.ts
+var OPS_WORDING = {
+  noun: "ops",
+  builder: "`opsRoute`",
+  factory: "createOpsRouter"
+};
+
 // src/ops/ops-route.ts
 var OPS_PATH_ROOT = "/_ops";
-function toOpsPath(path) {
-  if (!path.startsWith("/")) {
-    throw new OpsRouterError(
-      `Ops route path "${path}" must start with "/". It is appended to "${OPS_PATH_ROOT}", so "${path}" would read as "${OPS_PATH_ROOT}${path}".`
-    );
+var opsRoute = surfaceRouteBuilder(OPS_PATH_ROOT, OPS_WORDING);
+
+// src/ops/create-ops-router.ts
+var OPS_PATH_PREFIX = "/_ops/";
+var OPS_MANIFEST_PATH = "/_ops/_manifest";
+function moduleScopeGuard(authorize) {
+  if (!authorize) {
+    return void 0;
   }
-  if (path === "/") {
-    throw new OpsRouterError(
-      `Ops route path "/" names no command \u2014 "${OPS_PATH_ROOT}" itself is not a command.`
+  return (command) => command.module === void 0 ? void 0 : authorize(...command.scopes ?? []);
+}
+function createOpsRouter(routes, options) {
+  if ((options?.modules ?? []).length > 0 && !options.authorize) {
+    throw new SurfaceError(
+      "createOpsRouter requires an authorize scope factory when modules are mounted."
     );
   }
-  return OPS_PATH_ROOT + path;
+  return createSurface({
+    namespace: OPS_PATH_ROOT,
+    auth: options?.auth,
+    authorize: moduleScopeGuard(options?.authorize),
+    modules: options?.modules
+  }, OPS_WORDING, { requireEffect: false }).router(routes);
 }
-function opsMethod(method) {
-  return (path) => route[method](toOpsPath(path));
+
+// src/ops/manifest.ts
+function collectOpsCommands(routes) {
+  return collectSurfaceCommands(routes, OPS_WORDING);
+}
+
+// src/ops/module.ts
+function defineOpsModule(module) {
+  return validateSurfaceModule(module, OPS_PATH_ROOT, OPS_WORDING);
 }
-var opsRoute = {
-  get: opsMethod("get"),
-  post: opsMethod("post"),
-  put: opsMethod("put"),
-  patch: opsMethod("patch"),
-  delete: opsMethod("delete")
-};
 
-export { OPS_MANIFEST_PATH, OPS_PATH_PREFIX, OPS_PATH_ROOT, OpsRouterError, collectOpsCommands, createOpsRouter, opsRoute };
+export { OPS_MANIFEST_PATH, OPS_PATH_PREFIX, OPS_PATH_ROOT, SurfaceError as OpsRouterError, collectOpsCommands, createOpsRouter, defineOpsModule, opsRoute };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map