@spfn/core 0.3.0-beta.19 → 0.3.0-beta.20

package/dist/ops/index.js

@@ -283,6 +283,7 @@ function createRouterInstance(state) {
           newPackageRouters.push(...pkgRouter._packageRouters);
         }
       }
+      assertDistinctSurfaces(newPackageRouters);
       return createRouterInstance({ ...state, packageRouters: newPackageRouters });
     },
     use(middlewares) {
@@ -304,6 +305,21 @@ function assertContractVersion(version) {
     );
   }
 }
+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,
@@ -314,15 +330,25 @@ function defineUnmappedRouter(routes) {
   });
 }
 
-// src/ops/error.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/ops/manifest.ts
+// 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;
 }
@@ -346,22 +372,22 @@ 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,
@@ -370,43 +396,17 @@ function visit(routes, commands, claimed) {
     });
   }
 }
-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/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}".`
-    );
-  }
-  if (path === "/") {
-    throw new OpsRouterError(
-      `Ops route path "/" names no command \u2014 "${OPS_PATH_ROOT}" itself is not a command.`
-    );
-  }
-  return OPS_PATH_ROOT + path;
-}
-function opsMethod(method) {
-  return (path) => route[method](toOpsPath(path));
-}
-var opsRoute = {
-  get: opsMethod("get"),
-  post: opsMethod("post"),
-  put: opsMethod("put"),
-  patch: opsMethod("patch"),
-  delete: opsMethod("delete")
-};
-
-// src/ops/route-overlap.ts
+// src/surface/route-overlap.ts
 function routeSegments(path) {
   return path.split("/").slice(1).map((raw) => {
     if (raw === "*" || raw.endsWith("*")) {
@@ -441,7 +441,7 @@ function remainingStaticPath(segments, from) {
   const remaining = segments.slice(from);
   return remaining.every((segment) => segment.kind === "static") ? remaining.map((segment) => segment.value).join("/") : null;
 }
-function opsRoutePatternsOverlap(firstPath, secondPath) {
+function routePatternsOverlap(firstPath, secondPath) {
   const first = routeSegments(firstPath);
   const second = routeSegments(secondPath);
   const length = Math.max(first.length, second.length);
@@ -492,28 +492,28 @@ function opsRoutePatternsOverlap(firstPath, secondPath) {
   return true;
 }
 
-// src/ops/module.ts
+// 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 OPS_PATH_BASE = "https://spfn.invalid";
+var PATH_BASE = "https://spfn.invalid";
 function assertText(label, value) {
   if (typeof value !== "string" || value.trim().length === 0) {
-    throw new OpsRouterError(`${label} must be a non-empty string.`);
+    throw new SurfaceError(`${label} must be a non-empty string.`);
   }
 }
-function assertStableModulePath(moduleId, commandName, path) {
-  const label = `Ops command "${moduleId}.${commandName}" path "${path}"`;
+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, OPS_PATH_BASE);
+    url = new URL(transportPath, PATH_BASE);
   } catch {
-    throw new OpsRouterError(`${label} is not a valid URL path.`);
+    throw new SurfaceError(`${label} is not a valid URL path.`);
   }
-  if (url.origin !== OPS_PATH_BASE || url.search !== "" || url.hash !== "" || url.pathname !== transportPath) {
-    throw new OpsRouterError(`${label} is not a stable plain absolute 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;
@@ -522,89 +522,90 @@ function assertStableModulePath(moduleId, commandName, path) {
     try {
       next = decodeURIComponent(decoded);
     } catch {
-      throw new OpsRouterError(`${label} contains malformed percent encoding.`);
+      throw new SurfaceError(`${label} contains malformed percent encoding.`);
     }
     if (next.includes("\\") || (next.match(/\//g) ?? []).length !== slashCount || next.split("/").some((segment) => segment === "." || segment === "..")) {
-      throw new OpsRouterError(`${label} contains encoded path separators or dot segments.`);
+      throw new SurfaceError(`${label} contains encoded path separators or dot segments.`);
     }
     if (next === decoded) {
       return;
     }
     decoded = next;
   }
-  throw new OpsRouterError(`${label} uses too many percent-encoding layers.`);
+  throw new SurfaceError(`${label} uses too many percent-encoding layers.`);
 }
-function assertCliCallableModulePath(moduleId, commandName, path) {
+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 OpsRouterError(
-      `Ops 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.`
+    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(moduleId, name, command) {
+function assertCommand(at, moduleId, name, command) {
   if (!COMMAND_NAME.test(name)) {
-    throw new OpsRouterError(
-      `Ops module "${moduleId}" has invalid command name "${name}". Use dot-separated alphanumeric names.`
+    throw new SurfaceError(
+      `${at.label} module "${moduleId}" has invalid command name "${name}". Use dot-separated alphanumeric names.`
     );
   }
-  assertText(`Ops command "${moduleId}.${name}" summary`, command?.summary);
+  assertText(`${at.label} command "${moduleId}.${name}" summary`, command?.summary);
   if (!EFFECTS.has(command?.effect)) {
-    throw new OpsRouterError(
-      `Ops command "${moduleId}.${name}" has invalid effect ${JSON.stringify(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 OpsRouterError(`Ops command "${moduleId}.${name}" must declare at least one non-empty scope.`);
+    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 OpsRouterError(`Ops command "${moduleId}.${name}" must carry a complete ops route.`);
+    throw new SurfaceError(`${at.label} command "${moduleId}.${name}" must carry a complete route.`);
   }
-  assertStableModulePath(moduleId, name, route2.path);
-  assertCliCallableModulePath(moduleId, name, route2.path);
-  const modulePath = `${OPS_PATH_ROOT}/${moduleId}/`;
+  assertStableModulePath(at, moduleId, name, route2.path);
+  assertCliCallableModulePath(at, moduleId, name, route2.path);
+  const modulePath = `${at.namespace}/${moduleId}/`;
   if (!route2.path.startsWith(modulePath)) {
-    throw new OpsRouterError(
-      `Ops command "${moduleId}.${name}" is at "${route2.path}", outside "${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 OpsRouterError(`Ops command "${moduleId}.${name}" path climbs out of its module namespace.`);
+    throw new SurfaceError(`${at.label} command "${moduleId}.${name}" path climbs out of its module namespace.`);
   }
 }
-function defineOpsModule(module) {
+function validateSurfaceModule(module, namespace, wording = SURFACE_WORDING) {
+  const at = { namespace, label: capitalized(wording.noun) };
   if (!MODULE_ID.test(module?.id ?? "")) {
-    throw new OpsRouterError(
-      `Ops module id ${JSON.stringify(module?.id)} is invalid. Use lower-kebab-case.`
+    throw new SurfaceError(
+      `${at.label} module id ${JSON.stringify(module?.id)} is invalid. Use lower-kebab-case.`
     );
   }
-  assertText(`Ops module "${module.id}" source`, module.source);
-  assertText(`Ops module "${module.id}" summary`, module.summary);
+  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 OpsRouterError(
-      `Ops module "${module.id}" contractVersion must be a semantic version.`
+    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 OpsRouterError(`Ops module "${module.id}" commands must be an object.`);
+    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(module.id, name, command);
+    assertCommand(at, module.id, name, command);
     const signature = `${command.route.method} ${command.route.path}`;
     const existing = signatures.get(signature);
     if (existing) {
-      throw new OpsRouterError(
-        `Ops module "${module.id}" commands "${existing}" and "${name}" both use ${signature}.`
+      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 && opsRoutePatternsOverlap(claim.path, command.route.path));
+    const overlapping = claimedRoutes.find((claim) => claim.method === command.route.method && routePatternsOverlap(claim.path, command.route.path));
     if (overlapping) {
-      throw new OpsRouterError(
-        `Ops module "${module.id}" commands "${overlapping.name}" and "${name}" have overlapping ${command.route.method} routes ("${overlapping.path}" and "${command.route.path}").`
+      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({
@@ -616,180 +617,330 @@ function defineOpsModule(module) {
   return module;
 }
 
-// src/ops/create-ops-router.ts
-var OPS_PATH_PREFIX = "/_ops/";
-var OPS_MANIFEST_PATH = "/_ops/_manifest";
-var OPS_MANIFEST_NAME = "getOpsManifest";
+// 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
 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(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 (!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 === 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.`
+  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 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, guards, 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 = defineUnmappedRouter(
-    secureRoutes(router.routes, auth, handedDown)
+    secureRoutes(plan, router.routes, guards, handedDown)
   );
   if (router._contractVersion) {
     rebuilt = rebuilt.contractVersion(router._contractVersion);
   }
   return rebuilt;
 }
-function secureRoutes(routes, auth, inherited = []) {
+function secureRoutes(plan, routes, guards, 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, guards, 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);
     secured[name] = {
       ...entry,
-      middlewares: [auth, ...inherited, ...entry.middlewares ?? []]
+      middlewares: commandChain(plan, name, guards.get(name), [...inherited, ...entry.middlewares ?? []])
     };
   }
   return secured;
 }
-function compileModules(modules, appCommands) {
-  const descriptors = [];
-  const commands = [];
-  const routes = {};
+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 guardsFor(plan, commands) {
+  return new Map(commands.map((command) => [command.name, plan.authorize?.(command)]));
+}
+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 commandNames = new Set(appCommands.map((command) => command.name));
-  const routeSignatures = new Map(
-    appCommands.map((command) => [`${command.method} ${command.path}`, command.name])
-  );
-  for (const rawModule of modules) {
-    const module = defineOpsModule(rawModule);
+  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 OpsRouterError(`Two ops modules use id "${module.id}".`);
+      throw new SurfaceError(`Two ${plan.wording.noun} modules use id "${module.id}".`);
     }
     moduleIds.add(module.id);
-    descriptors.push({
+    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 name = `${module.id}.${localName}`;
-      if (commandNames.has(name)) {
-        throw new OpsRouterError(`Two ops commands are named "${name}".`);
-      }
-      commandNames.add(name);
-      const method = definition.route.method;
-      const path = definition.route.path;
-      const signature = `${method} ${path}`;
-      const existing = routeSignatures.get(signature);
-      if (existing) {
-        throw new OpsRouterError(
-          `Ops commands "${existing}" and "${name}" both use ${signature}.`
-        );
-      }
-      const overlappingAppCommand = appCommands.find((command) => command.method === method && opsRoutePatternsOverlap(command.path, path));
-      if (overlappingAppCommand) {
-        throw new OpsRouterError(
-          `App ops command "${overlappingAppCommand.name}" at ${method} ${overlappingAppCommand.path} overlaps module command "${name}" at ${method} ${path}. Which one answers cannot depend on route registration order.`
-        );
-      }
-      routeSignatures.set(signature, name);
-      commands.push({
-        name,
+      const command = {
+        name: `${module.id}.${localName}`,
         module: module.id,
         summary: definition.summary,
         effect: definition.effect,
         scopes: [...definition.scopes],
-        method,
-        path,
-        input: collectOpsCommands({ [localName]: definition.route })[0].input
-      });
-      routes[name] = { route: definition.route, scopes: definition.scopes };
+        method: definition.route.method,
+        path: definition.route.path,
+        input: collectSurfaceCommands({ [localName]: definition.route }, plan.wording)[0].input
+      };
+      assertModuleCommandFree(plan, command, appCommands, claimed);
+      compiled.commands.push(command);
+      compiled.routes[command.name] = { route: definition.route, command };
     }
   }
-  descriptors.sort((a, b) => a.id.localeCompare(b.id));
-  commands.sort((a, b) => a.name.localeCompare(b.name));
-  return { descriptors, commands, routes };
+  compiled.descriptors.sort((a, b) => a.id.localeCompare(b.id));
+  compiled.commands.sort((a, b) => a.name.localeCompare(b.name));
+  return compiled;
 }
-function secureModuleRoutes(routes, auth, authorize) {
+function secureModuleRoutes(plan, routes) {
   const secured = {};
   for (const [name, definition] of Object.entries(routes)) {
-    assertOpsName(name);
-    assertOpsRoute(name, definition.route);
+    assertSurfaceName(plan, name);
+    assertSurfaceRoute(plan, name, definition.route);
     secured[name] = {
       ...definition.route,
-      middlewares: [
-        auth,
-        authorize(...definition.scopes),
-        ...definition.route.middlewares ?? []
-      ]
+      middlewares: commandChain(
+        plan,
+        name,
+        plan.authorize?.(definition.command),
+        definition.route.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."
-    );
-  }
-  const modules = options.modules ?? [];
-  if (modules.length > 0 && !options.authorize) {
-    throw new OpsRouterError(
-      "createOpsRouter requires an authorize scope factory when modules are mounted."
-    );
-  }
-  const appCommands = collectOpsCommands(routes);
-  const moduleSurface = compileModules(modules, appCommands);
+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,
     ...moduleSurface.descriptors.length > 0 ? { modules: moduleSurface.descriptors } : {},
     commands
   };
-  const secured = secureRoutes(routes, options.auth);
-  const securedModules = moduleSurface.descriptors.length > 0 ? secureModuleRoutes(moduleSurface.routes, options.auth, options.authorize) : {};
-  const manifestRoute = route.get(OPS_MANIFEST_PATH).use([options.auth]).handler(async () => manifest);
-  return defineUnmappedRouter({
-    [OPS_MANIFEST_NAME]: manifestRoute,
+  const secured = secureRoutes(plan, routes, guardsFor(plan, appCommands));
+  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) {
+  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
+  };
+}
+function createSurface(options, wording) {
+  const plan = planOf(options, wording);
+  return {
+    namespace: plan.namespace,
+    route: surfaceRouteBuilder(plan.namespace, wording),
+    router: (routes) => buildRouter(plan, routes)
+  };
+}
+
+// src/ops/wording.ts
+var OPS_WORDING = {
+  noun: "ops",
+  builder: "`opsRoute`",
+  factory: "createOpsRouter"
+};
+
+// src/ops/ops-route.ts
+var OPS_PATH_ROOT = "/_ops";
+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;
+  }
+  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 createSurface({
+    namespace: OPS_PATH_ROOT,
+    auth: options?.auth,
+    authorize: moduleScopeGuard(options?.authorize),
+    modules: options?.modules
+  }, OPS_WORDING).router(routes);
+}
+
+// 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);
 }
 
-export { OPS_MANIFEST_PATH, OPS_PATH_PREFIX, OPS_PATH_ROOT, OpsRouterError, collectOpsCommands, createOpsRouter, defineOpsModule, 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