@velarscript/node 0.12.1 → 0.13.0

package/dist/serve-runtime.js

@@ -1,3 +1,4 @@
+import { ROUTE_SHAPE_FROM_SEGMENTS_SOURCE } from "./route-shape.js";
 // Application-facing velar/serve contract. HTTP sockets, request streams,
 // backpressure and static-file effects live in the shared isolated Node host;
 // this Realm owns only Velar values, handlers and strict JSON/type boundaries.
@@ -6,7 +7,7 @@ import { __velarNodeHostInvoke, __velarNodeHostOn } from "velar/node-host-v1";
 import { normalizeError as __velarServeNormalizeError } from "velar/compiler-runtime-errors-v1";
 import { __velarValidateDenseList as __velarServeValidateDenseList } from "velar/compiler-runtime-collection-lowering-v1";
 import { Bytes as __velarServeBytesType } from "velar/binary";
-import { writeBytes as __velarServeWriteBytes } from "velar/fs";
+import { canonical as __velarServeFsCanonical, info as __velarServeFsInfo, writeBytes as __velarServeWriteBytes } from "velar/fs";
 import { Cancellation as __velarServeCancellation } from "velar/task";
 
 const __velarServeArray = globalThis.Array;
@@ -186,9 +187,8 @@ function __velarServeIsSafeInteger(value) {
 }
 
 function __velarServeReserveOutbound(bytes) {
-  if (!__velarServeIsSafeInteger(bytes) || bytes < 0 || __velarServeOutboundBytes + bytes > __velarServeMaxOutboundBytes) {
-    throw new __velarServeRangeError("ServeResponse aggregate outbound byte budget is exhausted");
-  }
+  if (!__velarServeIsSafeInteger(bytes) || bytes < 0) throw new __velarServeRangeError("ServeResponse outbound byte reservation must be a non-negative integer");
+  if (__velarServeOutboundBytes + bytes > __velarServeMaxOutboundBytes) throw new __velarServeOutboundBudgetError();
   __velarServeOutboundBytes += bytes;
 }
 
@@ -430,6 +430,19 @@ export class HttpError extends __velarServeError {
   }
 }
 
+// Exhausting the aggregate outbound budget is a temporary load condition, not a
+// server fault: 503 with retry-after is what a load balancer and a client both
+// know how to act on, and 500 is what neither can. Most reserves happen while a
+// response is already on its way out, past the HttpError catch in
+// __velarServeHandleRequest, so both send paths recognize this one error by
+// identity and answer it themselves. The shed answer reserves nothing: it is a
+// fixed, tiny payload, and reserving for it would fail by construction.
+class __velarServeOutboundBudgetError extends HttpError {
+  constructor() {
+    super(503, {error: "outbound_budget_exhausted"}, new __velarServeMap([["retry-after", "1"]]));
+  }
+}
+
 function __velarServeIsFileResponse(value) {
   if (!value || typeof value !== "object") return false;
   const descriptor = __velarServeOwnDescriptor(value, __velarServeFileMarker);
@@ -600,6 +613,74 @@ function __velarServeIsUpload(value) {
 
 export const Upload = __velarServeTypeObject(__velarServeIsUpload, "Upload values are created from multipart route inputs");
 
+// Upload.save takes its containment root as a required argument and refuses any
+// target that resolves outside it. The host operations bag __velarServeNativeFile
+// uses for static files is not reachable from this Realm, so containment is
+// composed from velar/fs instead of a new host operation: fail-closed textual
+// rules on the caller's path, then a canonical check of the directory that will
+// hold the file so a symbolic link cannot lead out of the root. That is the
+// smaller of the two shapes and adds no trust boundary. This is complementary to
+// the basename reduction in __velarServeUploadBasename, which bounds only what a
+// client can put into Upload.filename.
+function __velarServeUploadSegments(path) {
+  if (typeof path !== "string" || path.length === 0) throw new __velarServeTypeError("Upload.save path must be a non-empty path relative to its root");
+  if (path.length > __velarServeMaxPathCodeUnits || __velarServeCall(__velarServeStringIncludes, path, ["\0"])) {
+    throw new __velarServeRangeError("Upload.save path is outside the supported bounds");
+  }
+  // The root's separator is a host detail this Realm cannot consult, so both
+  // separators are refused, exactly as __velarServeNativeEscapes refuses both.
+  // Only '..' and an absolute path genuinely leave the root; a backslash, an
+  // empty segment and a '.' are refused because this Realm will not normalize a
+  // path on the caller's behalf, so each refusal says which of the two it is
+  // rather than naming an escape that did not happen.
+  if (__velarServeCall(__velarServeStringIncludes, path, ["\\"])) throw new __velarServeError("Upload.save path cannot contain a backslash: it is a path separator on some hosts");
+  if (__velarServeCall(__velarServeStringStartsWith, path, ["/"])) throw new __velarServeError("Upload.save path escapes its root: it is absolute");
+  const segments = __velarServeCall(__velarServeStringSplit, path, ["/"]);
+  for (let index = 0; index < segments.length; index += 1) {
+    const segment = segments[index];
+    if (segment === "..") throw new __velarServeError("Upload.save path escapes its root: it has a '..' segment");
+    if (segment === "") throw new __velarServeError("Upload.save path must be normalized: it has an empty segment");
+    if (segment === ".") throw new __velarServeError("Upload.save path must be normalized: it has a '.' segment");
+  }
+  return segments;
+}
+
+function __velarServeUploadContains(root, target) {
+  if (target === root) return true;
+  if (target.length <= root.length || __velarServeCall(__velarServeStringSlice, target, [0, root.length]) !== root) return false;
+  const boundary = __velarServeCall(__velarServeStringSlice, target, [root.length, root.length + 1]);
+  return boundary === "/" || boundary === "\\";
+}
+
+async function __velarServeUploadTarget(path, root) {
+  const segments = __velarServeUploadSegments(path);
+  if (typeof root !== "string" || root.length === 0) throw new __velarServeTypeError("Upload.save root must be a non-empty directory path");
+  // Resolution failures arrive from the host as an errno naming an absolute path
+  // the caller never wrote, so both are answered in the caller's own terms: the
+  // root it named, or the relative directory it asked for.
+  let base;
+  try { base = await __velarServeFsCanonical(root); }
+  catch { throw new __velarServeError("Upload.save root does not resolve to an existing directory"); }
+  let directory = base;
+  let relative = "";
+  for (let index = 0; index + 1 < segments.length; index += 1) {
+    directory += "/" + segments[index];
+    relative += relative === "" ? segments[index] : "/" + segments[index];
+  }
+  if (directory !== base) {
+    try { directory = await __velarServeFsCanonical(directory); }
+    catch { throw new __velarServeError("Upload.save path names a directory that does not exist under the root: " + relative); }
+    if (!__velarServeUploadContains(base, directory)) throw new __velarServeError("Upload.save path escapes its root through a symbolic link");
+  }
+  const target = directory + "/" + segments[segments.length - 1];
+  // A write follows a symbolic link at the target itself, so the last segment is
+  // canonicalized by kind rather than by path: refusing the link is fail-closed
+  // and needs no second containment test.
+  const existing = await __velarServeFsInfo(target);
+  if (existing !== null && existing.kind === "symlink") throw new __velarServeError("Upload.save refuses to write through a symbolic link");
+  return target;
+}
+
 function __velarServeUploadValue(name, filename, contentType, data, states) {
   if (!__velarServeBytesType.is(data)) throw new __velarServeTypeError("Upload data must be Bytes");
   const state = {data};
@@ -620,7 +701,11 @@ function __velarServeUploadValue(name, filename, contentType, data, states) {
       catch { throw new __velarServeTypeError("Upload is not valid UTF-8 text"); }
     },
     bytes: async () => __velarServeBytesType.parse(current()),
-    save: async path => { await __velarServeWriteBytes(path, current()); return null; },
+    save: async (path, root) => {
+      const value = current();
+      await __velarServeWriteBytes(await __velarServeUploadTarget(path, root), value);
+      return null;
+    },
   }]);
 }
 
@@ -929,12 +1014,13 @@ function __velarServeRoutePath(path, name = "Route path") {
   return path;
 }
 
+// D90 R19(c): the shape rule is written once, in route-shape.ts, and this
+// module interpolates that one definition. The shared core touches only
+// indexed access and .length, so it stays sound inside this hardened Realm;
+// the split it never performs itself happens here with the captured split.
+const __velarServeRouteShapeFromSegments = ${ROUTE_SHAPE_FROM_SEGMENTS_SOURCE};
 function __velarServeRouteShape(path) {
-  const segments = __velarServeCall(__velarServeStringSplit, path, ["/"]);
-  for (let index = 1; index < segments.length; index += 1) {
-    if (__velarServeCall(__velarServeStringStartsWith, segments[index], ["{"]) && __velarServeCall(__velarServeStringEndsWith, segments[index], ["}"])) segments[index] = "{}";
-  }
-  return __velarServeCall(__velarServeArrayJoin, segments, ["/"]);
+  return __velarServeRouteShapeFromSegments(__velarServeCall(__velarServeStringSplit, path, ["/"]));
 }
 
 function __velarCreateServeRoute(method, path, parameters, handler, metadata = {}) {
@@ -1158,23 +1244,33 @@ function __velarCreateServeApp(name, items) {
   const routes = [];
   const lifecycles = [];
   let notFound = null;
+  // D90 R19(b): assembly is the moment the final table exists, so the final
+  // table is judged here — a conflict names both routes and both origins,
+  // because the statically invisible half of a collision is exactly the one
+  // the author cannot see in his own file.
   const shapes = new __velarServeMap();
-  const append = route => {
+  const describeRoute = entry => "'" + entry.route.method + " " + entry.route.path + "'"
+    + (entry.source === null ? " declared by this server" : " composed in from '" + entry.source + "'");
+  const append = (route, source) => {
     if (routes.length >= __velarServeMaxRoutes) throw new __velarServeRangeError("ServeApp cannot contain more than 4096 routes after composition");
     const key = route.method + " " + __velarServeRouteShape(route.path);
-    if (__velarServeCall(__velarServeMapHas, shapes, [key])) throw new __velarServeTypeError("ServeApp contains conflicting route '" + key + "'");
-    __velarServeCall(__velarServeMapSet, shapes, [key, true]);
+    const previous = __velarServeCall(__velarServeMapGet, shapes, [key]);
+    if (previous !== undefined) {
+      throw new __velarServeTypeError("ServeApp '" + name + "' contains conflicting routes: " + describeRoute({route, source})
+        + " and " + describeRoute(previous) + " both answer '" + key + "' — narrow or remove one");
+    }
+    __velarServeCall(__velarServeMapSet, shapes, [key, {route, source}]);
     routes[routes.length] = route;
   };
   for (let index = 0; index < items.length; index += 1) {
     const item = items[index];
-    if (__velarServeIsRoute(item)) append(item);
+    if (__velarServeIsRoute(item)) append(item, null);
     else if (__velarServeIsNotFound(item)) {
       if (notFound !== null) throw new __velarServeTypeError("ServeApp contains more than one @notFound fallback");
       notFound = item;
     }
     else if (__velarServeIsApp(item)) {
-      for (let route = 0; route < item.routes.length; route += 1) append(item.routes[route]);
+      for (let route = 0; route < item.routes.length; route += 1) append(item.routes[route], item.name);
       for (let hook = 0; hook < item.lifecycles.length; hook += 1) {
         if (lifecycles.length >= __velarServeMaxLifecycles) throw new __velarServeRangeError("ServeApp cannot contain more than 4096 lifecycle pairs after composition");
         lifecycles[lifecycles.length] = item.lifecycles[hook];
@@ -1336,6 +1432,7 @@ function __velarServeCors(origins = ["*"], methods = ["GET", "POST", "PUT", "PAT
   methods = __velarServeStringList(methods, "middleware.cors methods");
   headers = __velarServeStringList(headers, "middleware.cors headers");
   if (typeof credentials !== "boolean" || !__velarServeIsSafeInteger(maxAge) || maxAge < 0 || maxAge > 86400) throw new __velarServeTypeError("middleware.cors options are invalid");
+  if (credentials && __velarServeCall(__velarServeArrayIncludes, origins, ["*"])) throw new __velarServeTypeError("middleware.cors cannot combine credentials with the '*' origin wildcard");
   return async (request, next) => {
     const origin = __velarServeCall(__velarServeMapHas, request.headers, ["origin"]) ? __velarServeCall(__velarServeMapGet, request.headers, ["origin"]) : null;
     const wildcard = __velarServeCall(__velarServeArrayIncludes, origins, ["*"]);
@@ -1466,18 +1563,26 @@ function __velarServeTimeout(milliseconds) {
     if (__velarServeActiveTimeouts >= __velarServeMaxActiveTimeouts) {
       return {status: 503, json: {error: "server_busy"}, headers: new __velarServeMap([["retry-after", "1"]])};
     }
-    __velarServeActiveTimeouts += 1;
     let timer = null;
-    let detached = false;
-    let pending;
-    try { pending = next(); }
-    catch (error) { __velarServeActiveTimeouts -= 1; throw error; }
+    const pending = next();
     const expired = new __velarServePromise(resolve => { timer = __velarServeCall(__velarServeSetTimeout, globalThis, [() => resolve(__velarServeMissing), milliseconds]); });
     try {
       const result = await __velarServeCall(__velarServePromiseRace, __velarServePromise, [__velarServeCall(__velarServeObjectFreeze, __velarServeObject, [[pending, expired]])]);
       if (result !== __velarServeMissing) return result;
-      detached = true;
       __velarServeCancellation.__velarCancel(request.cancellation, "Request timed out");
+      // The published bound counts unfinished timed-out continuations, and the
+      // background reservation at __velarServeRunBackground subtracts exactly
+      // this many slots from the process total. Admission alone cannot hold
+      // that count: a burst admitted while nothing was detached can expire
+      // together. When the detached budget is full the request has already been
+      // cancelled, so wait for it to unwind here instead of detaching work the
+      // process no longer accounts for.
+      if (__velarServeActiveTimeouts >= __velarServeMaxActiveTimeouts) {
+        try { await pending; }
+        catch (error) { __velarServeReportFailure(error); }
+        return {status: 504, json: {error: "request_timeout"}};
+      }
+      __velarServeActiveTimeouts += 1;
       __velarServeActiveBackgroundTasks += 1;
       const settlement = (async () => {
         try { await pending; }
@@ -1500,7 +1605,6 @@ function __velarServeTimeout(milliseconds) {
       };
     } finally {
       if (timer !== null) __velarServeCall(__velarServeClearTimeout, globalThis, [timer]);
-      if (!detached) __velarServeActiveTimeouts -= 1;
     }
   };
 }
@@ -1604,15 +1708,19 @@ function __velarServeDecodeScalar(raw, parameter) {
 function __velarServeCookieValue(request, name) {
   if (!__velarServeCall(__velarServeMapHas, request.headers, ["cookie"])) return __velarServeMissing;
   const pieces = __velarServeCall(__velarServeStringSplit, __velarServeCall(__velarServeMapGet, request.headers, ["cookie"]), [";"]);
+  let encoded = null;
+  let matches = 0;
   for (let index = 0; index < pieces.length; index += 1) {
     const piece = __velarServeCall(__velarServeStringTrim, pieces[index], []);
     const separator = __velarServeCall(__velarServeStringIndexOf, piece, ["="]);
     if (separator < 0 || __velarServeCall(__velarServeStringSlice, piece, [0, separator]) !== name) continue;
-    const encoded = __velarServeCall(__velarServeStringSlice, piece, [separator + 1]);
-    try { return __velarServeCall(__velarServeDecodeURIComponent, undefined, [encoded]); }
-    catch { throw new HttpError(400, {error: "invalid_cookie", parameter: name}); }
+    matches += 1;
+    if (matches > 1) throw new HttpError(400, {error: "duplicate_cookie", parameter: name});
+    encoded = __velarServeCall(__velarServeStringSlice, piece, [separator + 1]);
   }
-  return __velarServeMissing;
+  if (matches === 0) return __velarServeMissing;
+  try { return __velarServeCall(__velarServeDecodeURIComponent, undefined, [encoded]); }
+  catch { throw new HttpError(400, {error: "invalid_cookie", parameter: name}); }
 }
 
 function __velarServeNamedInputRaw(descriptor, parameterName, request) {
@@ -1813,6 +1921,17 @@ function __velarServeMultipartHeaders(text) {
   return output;
 }
 
+function __velarServeUploadBasename(filename) {
+  // A client may send a full path, including a Windows path with backslashes.
+  // An Upload name is one file name, never a path an application can compose
+  // into a directory it did not intend to write.
+  const slashed = __velarServeCall(__velarServeStringSplit, filename, ["/"]);
+  const separated = __velarServeCall(__velarServeStringSplit, slashed[slashed.length - 1], ["\\"]);
+  const base = separated[separated.length - 1];
+  if (base === "" || base === "." || base === ".." || __velarServeCall(__velarServeStringIncludes, base, ["\0"])) throw new HttpError(400, {error: "invalid_multipart"});
+  return base;
+}
+
 function __velarServeMultipart(data, boundary) {
   const opening = __velarServeBytePattern("--" + boundary);
   const separator = __velarServeBytePattern("\r\n\r\n");
@@ -1844,8 +1963,9 @@ function __velarServeMultipart(data, boundary) {
       __velarServeAddFormField(fields, name, __velarServeDecodeBytes(part));
     } else {
       if (filename.length > 1024 || __velarServeCall(__velarServeMapHas, files, [name])) throw new HttpError(400, {error: "invalid_multipart"});
+      const base = __velarServeUploadBasename(filename);
       const contentType = typeof headers["content-type"] === "string" ? headers["content-type"] : "application/octet-stream";
-      __velarServeCall(__velarServeMapSet, files, [name, __velarServeUploadValue(name, filename, contentType, part, uploadStates)]);
+      __velarServeCall(__velarServeMapSet, files, [name, __velarServeUploadValue(name, base, contentType, part, uploadStates)]);
     }
     parts += 1;
     if (parts > 128) throw new HttpError(413, {error: "too_many_form_parts"});
@@ -2024,14 +2144,22 @@ function __velarServeJsonContentType(headers) {
     || __velarServeCall(__velarServeStringStartsWith, value, ["application/"]) && __velarServeCall(__velarServeStringEndsWith, value, ["+json"]);
 }
 
+function __velarServeIsResponseAttempt(value) {
+  if (!value || typeof value !== "object" || __velarServeIsArray(value)) return false;
+  if (!__velarServeOwnDescriptor(value, "status")) return false;
+  return !!(__velarServeOwnDescriptor(value, "json") || __velarServeOwnDescriptor(value, "text") || __velarServeOwnDescriptor(value, "stream"));
+}
+
 function __velarServeAutomaticResponse(value) {
   if (__velarServeIsFileResponse(value)) return value;
+  if (__velarServeIsResponseAttempt(value)) return __velarServeResponse(value);
   try { return __velarServeResponse(value); }
   catch { return __velarServeResponse({status: 200, json: value}); }
 }
 
 function __velarServeNotFoundResponse(value) {
   if (__velarServeIsFileResponse(value)) return value;
+  if (__velarServeIsResponseAttempt(value)) return __velarServeResponse(value);
   try { return __velarServeResponse(value); }
   catch { return __velarServeResponse({status: 404, json: value}); }
 }
@@ -2081,6 +2209,7 @@ async function __velarServeHandleAppResponse(app, request, maxBodyBytes, context
     return await __velarServeApplyMiddleware(selected.route, request, invokeRoute);
   } catch (error) {
     if (error instanceof HttpError) return {status: error.status, json: error.body, headers: error.headers};
+    if (error instanceof RequestBodyTooLargeError) return {status: 413, json: {error: "request_too_large"}};
     throw error;
   }
 }
@@ -2612,6 +2741,16 @@ function __velarServeRequest(value) {
   }])};
 }
 
+// The budget error can also surface after a response has started, where the host
+// refuses a second terminal response; that attempt fails and the request falls
+// through to the opaque failure exactly as any other late error does.
+async function __velarServeShedOutbound(handle) {
+  try {
+    await __velarNodeHostInvoke("serve.respond", [handle, 503, [["retry-after", "1"]], "json", '{"error":"outbound_budget_exhausted"}', null, null, []]);
+    return true;
+  } catch { return false; }
+}
+
 async function __velarServeWriteResponse(handle, value) {
   let cleanup = null;
   let backgroundTasks = null;
@@ -2681,7 +2820,8 @@ function __velarServeNativeHeaders(request) {
   return output;
 }
 
-function __velarServeNativeRequest(request) {
+function __velarServeNativeRequest(request, maximum = __velarServeMaxBodyBytes) {
+  maximum = __velarServeBodyLimit(maximum);
   const method = request.method ?? "GET";
   if (typeof method !== "string" || !__velarServeCall(__velarServeRegExpTest, __velarServeMethodPattern, [method])) throw new __velarServeTypeError("Native HTTP method is invalid");
   const target = request.url ?? "/";
@@ -2698,7 +2838,7 @@ function __velarServeNativeRequest(request) {
       try {
         for await (const chunk of request) {
           const data = chunk instanceof __velarServeUint8Array ? chunk : __velarServeCall(__velarServeTextEncode, __velarServeUtf8Encoder, [__velarServeString(chunk)]);
-          if (total + data.byteLength > __velarServeMaxBodyBytes) { request.resume(); throw new RequestBodyTooLargeError(__velarServeMaxBodyBytes); }
+          if (total + data.byteLength > maximum) { request.resume(); throw new RequestBodyTooLargeError(maximum); }
           __velarServeReserveOutbound(data.byteLength);
           total += data.byteLength;
           reservedBodyBytes += data.byteLength;
@@ -2721,20 +2861,21 @@ function __velarServeNativeRequest(request) {
     })();
     return await bodyPromise;
   };
-  const bytes = async (maxBytes = __velarServeMaxBodyBytes) => {
+  const bytes = async (maxBytes = maximum) => {
     if (!__velarServeIsSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > __velarServeMaxBodyBytes) throw new __velarServeRangeError("Request body maxBytes must be an integer from 1 through 16777216");
     const data = await rawBody();
-    if (data.byteLength > maxBytes) throw new RequestBodyTooLargeError(maxBytes);
+    const effective = maxBytes > maximum ? maximum : maxBytes;
+    if (data.byteLength > effective) throw new RequestBodyTooLargeError(effective);
     return data;
   };
-  const body = async (maxBytes = __velarServeMaxBodyBytes) => {
+  const body = async (maxBytes = maximum) => {
     const data = await bytes(maxBytes);
     try { return __velarServeCall(__velarServeTextDecode, __velarServeUtf8Decoder, [data]); }
     catch { throw new __velarServeTypeError("Request body must be valid UTF-8 text"); }
   };
-  const json = async (maxBytes = __velarServeMaxBodyBytes) => __velarJsonParse(await body(maxBytes), "ServeRequest JSON text");
+  const json = async (maxBytes = maximum) => __velarJsonParse(await body(maxBytes), "ServeRequest JSON text");
   return {
-    request: __velarServeCall(__velarServeObjectFreeze, __velarServeObject, [{method, path, query: query.values, queryAll: query.all, headers: __velarServeNativeHeaders(request), cancellation, text: body, bytes, json, parse: async (Type, maxBytes = __velarServeMaxBodyBytes) => { Type = __velarRequireRuntimeType(Type, "ServeRequest.parse"); return Type.parse(await json(maxBytes)); }}]),
+    request: __velarServeCall(__velarServeObjectFreeze, __velarServeObject, [{method, path, query: query.values, queryAll: query.all, headers: __velarServeNativeHeaders(request), cancellation, text: body, bytes, json, parse: async (Type, maxBytes = maximum) => { Type = __velarRequireRuntimeType(Type, "ServeRequest.parse"); return Type.parse(await json(maxBytes)); }}]),
     cancellation,
     cleanup() { if (reservedBodyBytes > 0) { __velarServeReleaseOutbound(reservedBodyBytes); reservedBodyBytes = 0; } return null; },
   };
@@ -2749,14 +2890,49 @@ function __velarServeNativeSetHeaders(response, headers, cookies = []) {
   for (let index = 0; index < cookies.length; index += 1) allCookies[allCookies.length] = cookies[index];
   if (allCookies.length > 0) response.setHeader("Set-Cookie", allCookies);
 }
+// Every error branch of __velarServeHandleNative answers with a body of its own,
+// so it has to start from an empty header set: a content-length staged for the
+// response that failed makes the client wait for bytes that will never arrive,
+// and a Set-Cookie staged by a handler whose request was never served hands out
+// a session for nothing. The isolated-host transport gets this for free — it
+// sheds before the host ever sets a header — so this is the native transport
+// reaching the same state.
+function __velarServeNativeResetHeaders(response) {
+  const names = response.getHeaderNames();
+  for (let index = 0; index < names.length; index += 1) response.removeHeader(names[index]);
+}
+class __velarServeNativeNotFound extends __velarServeError {}
+function __velarServeNativeMissing(error) {
+  const code = error?.code;
+  return code === "ENOENT" || code === "ENOTDIR" || code === "EISDIR";
+}
+// A relative path carries .. only as a whole segment, so a bare two-dot prefix
+// test also refuses an ordinary top-level file whose own name begins with two
+// dots — the same over-strict form the host worker's containment check carried.
+// The operations bag has no separator to consult and may come from a bridge
+// embedding, so both separators are refused: fail closed on Windows rather than
+// trust a default.
+function __velarServeNativeEscapes(path, operations) {
+  return path === ".." || path.startsWith("../") || path.startsWith("..\\") || operations.isAbsolute(path);
+}
 async function __velarServeNativeFile(value, operations) {
-  const root = await operations.realpath(operations.resolve(value.root));
+  let root;
+  // A static root that does not exist is the same miss as a file that does not
+  // exist: reporting it as a failure would answer 500 and write the absolute
+  // deployment path to stderr, which the host transport never does.
+  try { root = await operations.realpath(operations.resolve(value.root)); }
+  catch (error) { if (__velarServeNativeMissing(error)) throw new __velarServeNativeNotFound("fileResponse root does not name a directory"); throw error; }
   const load = async path => {
-    const target = await operations.realpath(operations.resolve(root, path.startsWith("/") ? "." + path : path));
+    let target;
+    try { target = await operations.realpath(operations.resolve(root, path.startsWith("/") ? "." + path : path)); }
+    catch (error) { if (__velarServeNativeMissing(error)) throw new __velarServeNativeNotFound("fileResponse path does not name a file"); throw error; }
     const relative = operations.relative(root, target);
-    if (relative.startsWith("..") || operations.isAbsolute(relative)) throw new __velarServeTypeError("fileResponse path escapes its root");
-    const info = await operations.stat(target);
-    if (!info.isFile() || info.size > 64 * 1024 * 1024) throw new __velarServeRangeError("fileResponse file exceeds 64 MiB");
+    if (__velarServeNativeEscapes(relative, operations)) throw new __velarServeNativeNotFound("fileResponse path escapes its root");
+    let info;
+    try { info = await operations.stat(target); }
+    catch (error) { if (__velarServeNativeMissing(error)) throw new __velarServeNativeNotFound("fileResponse path does not name a file"); throw error; }
+    if (!info.isFile()) throw new __velarServeNativeNotFound("fileResponse path does not name a file");
+    if (info.size > 64 * 1024 * 1024) throw new __velarServeRangeError("fileResponse file exceeds 64 MiB");
     return {target, info};
   };
   try { return await load(value.path); } catch (error) { if (value.fallback === null) throw error; return load(value.fallback); }
@@ -2826,13 +3002,13 @@ async function __velarServeNativeBody(response, value, checked, suppressBody, op
   if (!response.hasHeader("vary")) response.setHeader("vary", "Accept-Encoding");
   return __velarServeWithOutbound(compressed.byteLength, () => __velarServeNativeEnd(response, compressed));
 }
-async function __velarServeHandleNative(handler, request, response, operations) {
+async function __velarServeHandleNative(handler, request, response, operations, maxBodyBytes = __velarServeMaxBodyBytes) {
   let cleanup = null;
   let backgroundTasks = null;
   let incoming = null;
   let disconnected = null;
   try {
-    incoming = __velarServeNativeRequest(request);
+    incoming = __velarServeNativeRequest(request, maxBodyBytes);
     disconnected = () => { if (!response.writableFinished) __velarServeCancellation.__velarCancel(incoming.cancellation, "client_disconnect"); };
     request.once("aborted", disconnected);
     response.once("close", disconnected);
@@ -2847,7 +3023,34 @@ async function __velarServeHandleNative(handler, request, response, operations)
     let writing = false;
     const write = async chunk => { if (writing) throw new __velarServeError("ServeResponse allows only one active stream write"); writing = true; try { if (typeof chunk !== "string" || __velarUtf8ByteLength(chunk) > 1024 * 1024) throw new __velarServeTypeError("ServeResponse.stream chunks must be text of at most 1 MiB"); if (!suppressBody) await __velarServeWithOutbound(__velarUtf8ByteLength(chunk), () => __velarServeNativeWrite(response, chunk)); return null; } finally { writing = false; } };
     const result = await checked.stream(write); if (result !== null) throw new __velarServeTypeError("ServeResponse.stream producer must resolve to null"); if (writing) throw new __velarServeError("ServeResponse stream producer returned before its write completed"); await __velarServeNativeEnd(response); return null;
-  } catch (error) { __velarServeReportFailure(error); if (!response.headersSent) { response.statusCode = 500; response.setHeader("content-type", "text/plain; charset=utf-8"); response.end("Internal server error"); } else response.destroy(); return null; }
+  } catch (error) {
+    if (error instanceof RequestBodyTooLargeError && !response.headersSent) {
+      __velarServeNativeResetHeaders(response);
+      response.statusCode = 413;
+      response.setHeader("content-type", "application/json; charset=utf-8");
+      response.end(request.method === "HEAD" ? undefined : '{"error":"request_too_large"}');
+      return null;
+    }
+    if (error instanceof __velarServeNativeNotFound && !response.headersSent) {
+      __velarServeNativeResetHeaders(response);
+      response.statusCode = 404;
+      response.setHeader("content-type", "text/plain; charset=utf-8");
+      response.end(request.method === "HEAD" ? undefined : "Not found");
+      return null;
+    }
+    if (error instanceof __velarServeOutboundBudgetError && !response.headersSent) {
+      __velarServeNativeResetHeaders(response);
+      response.statusCode = 503;
+      response.setHeader("retry-after", "1");
+      response.setHeader("content-type", "application/json; charset=utf-8");
+      response.end(request.method === "HEAD" ? undefined : '{"error":"outbound_budget_exhausted"}');
+      return null;
+    }
+    __velarServeReportFailure(error);
+    if (!response.headersSent) { __velarServeNativeResetHeaders(response); response.statusCode = 500; response.setHeader("content-type", "text/plain; charset=utf-8"); response.end("Internal server error"); }
+    else response.destroy();
+    return null;
+  }
   finally {
     if (disconnected !== null) { request.off("aborted", disconnected); response.off("close", disconnected); }
     await __velarServeRunBackground(backgroundTasks);
@@ -3129,6 +3332,7 @@ async function __velarServeDispatch(event) {
   if (typeof handler !== "function") { __velarServeReportFailure(new __velarServeError("Node host requested an unknown server token")); await __velarNodeHostInvoke("serve.fail", [value.handle]); return; }
   try { await __velarServeWriteResponse(value.handle, await handler(value.request)); }
   catch (error) {
+    if (error instanceof __velarServeOutboundBudgetError && await __velarServeShedOutbound(value.handle)) return;
     __velarServeReportFailure(error);
     try { await __velarNodeHostInvoke("serve.fail", [value.handle]); }
     catch {}

package/dist/serve-runtime.js.map

@@ -1 +1 @@
-{"version":3,"file":"serve-runtime.js","sourceRoot":"","sources":["../src/serve-runtime.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,8EAA8E;AAC9E,+EAA+E;AAC/E,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0qGjD,CAAC,SAAS,EAAE,CAAC"}
+{"version":3,"file":"serve-runtime.js","sourceRoot":"","sources":["../src/serve-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gCAAgC,EAAE,MAAM,kBAAkB,CAAC;AAEpE,0EAA0E;AAC1E,8EAA8E;AAC9E,+EAA+E;AAC/E,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6CAw/BL,gCAAgC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA63E5E,CAAC,SAAS,EAAE,CAAC"}

package/dist/server-analyzer.d.ts

@@ -18,6 +18,16 @@ export declare function parseRouteResultHint(value: string | undefined): {
 export declare class VelarNodeAnalyzer extends Analyzer {
     private readonly contextualRouteParameters;
     private readonly routeInputs;
+    /** Servers declared by the module under analysis, the only spread targets this analyzer can resolve. */
+    private readonly moduleServers;
+    /** Module-level `const alias = name` and `let alias = name` bindings, so a spread of an alias resolves to the server it names. */
+    private readonly moduleServerAliases;
+    /** Local names imported from velar/serve that name a path-preserving combinator, so a spread of a call resolves through it. */
+    private readonly moduleServeCombinators;
+    /** One answer per `let` alias name to "was this binding ever reassigned?", because the predicate walks the whole program. */
+    private readonly stableAliases;
+    /** The program under analysis, held for the alias-stability walk. */
+    private moduleProgram;
     private readonly nodeModulePath;
     constructor(context?: AnalysisContext, extensions?: readonly CompilerAnalysisExtension[]);
     analyze(program: Program): readonly import("@velarscript/compiler").Diagnostic[];
@@ -27,6 +37,47 @@ export declare class VelarNodeAnalyzer extends Analyzer {
         readonly kind: string;
     }, parameter: Parameter): ValueType | null;
     private analyzeServer;
+    /**
+     * Enters one route into this server's shape map and compares it against every route already
+     * entered, whether that route was written here or composed in by a spread. Composition is why the
+     * entries carry an origin: a conflicting route the author cannot see in his own file has to name
+     * the server it came from.
+     */
+    private recordRoute;
+    /**
+     * The routes and fallback a spread composes into the server that writes it, or null when the
+     * spread is not statically resolvable. This analyzer sees one module, so a spread contributes
+     * only when its value reaches a server declared in this module: a plain identifier, an alias of
+     * one, or a velar/serve combinator call around one — `use`, `bodyLimit`, `docs` and `lifecycle`
+     * carry paths through unchanged, and `prefix` translates them by its literal path. An imported
+     * server, a computed prefix path, or any other expression is let through unchecked, because a
+     * false conflict here would block a correct program; D90 R19's runtime referee judges the final
+     * table at assembly instead. Composition is followed transitively; the visited set bounds a
+     * cycle and starts holding the composing server, so a cycle never folds a server's own routes
+     * back into itself and reports each as conflicting with itself.
+     */
+    private composedItems;
+    /**
+     * The server declaration a spread value names, or null when it is anything else. A
+     * `const other = base` alias chain of this module's own servers resolves too, because the alias
+     * holds exactly that ServeApp — and so does a `let` alias the whole module never reassigns,
+     * because an unwritten `let` holds its initializer exactly as a `const` does. A reassigned or
+     * ambiguous `let`, a member path, a conditional, an import, or a parameter contributes nothing.
+     * A call resolves through the path-preserving velar/serve combinators when the callee still
+     * reaches its velar/serve import: `prefix` with a literal path translates what its app argument
+     * declares, and `use`/`bodyLimit`/`docs`/`lifecycle` pass it through untouched. A computed
+     * prefix path contributes nothing — the assembly-time referee owns it. An alias's initializer
+     * re-enters this resolver whole, so `const scoped = prefix("/api", routes)` resolves exactly as
+     * the spelled-out spread does; the followed set bounds an alias cycle.
+     */
+    private resolveComposedServer;
+    /** Whether a `let` alias has never been reassigned, asked once per name and program. */
+    private aliasBindingIsStable;
+    /**
+     * Whether a name still reaches the declaration this module recorded for it. An import, a
+     * shadowing binding, or a parameter of the same name reaches a different binding.
+     */
+    private resolvesTo;
     private analyzeNotFound;
     private analyzeRoute;
 }

package/dist/server-analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-analyzer.d.ts","sourceRoot":"","sources":["../src/server-analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EASR,KAAK,eAAe,EACpB,KAAK,yBAAyB,EAC9B,KAAK,gCAAgC,EACrC,KAAK,SAAS,EACd,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,iCAAiC,CAAC;AAyBzC,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,YAAY,GAAG,UAAU,CAAC;AAC/I,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,YAAY,GAAG,UAAU,CAAC;AAC5I,KAAK,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEvD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,oBAAoB,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,EAAE,aAAa,EAAE,UAAU,UAAQ,GAAG,MAAM,CAE5I;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG;IAClE,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B,GAAG,IAAI,CAcP;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAErH;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG;IAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAC,GAAG,IAAI,CAWjL;AAED,qBAAa,iBAAkB,SAAQ,QAAQ;IAC7C,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAgC;IAC1E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyC;IACrE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgB;IAE/C,YAAY,OAAO,GAAE,eAAoB,EAAE,UAAU,GAAE,SAAS,yBAAyB,EAAO,EAG/F;IAEQ,OAAO,CAAC,OAAO,EAAE,OAAO,yDAShC;IAED,UAAmB,4BAA4B,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAI7E;IAED,UAAmB,yBAAyB,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAI1E;IAED,UAAmB,kCAAkC,CACnD,SAAS,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EACpC,SAAS,EAAE,SAAS,GACnB,SAAS,GAAG,IAAI,CAYlB;IAED,OAAO,CAAC,aAAa;IAgCrB,OAAO,CAAC,eAAe;IAwBvB,OAAO,CAAC,YAAY;CAqGrB;AAID,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,gCAAgC,GAAG,SAAS,GAAG,SAAS,CA0KnG"}
+{"version":3,"file":"server-analyzer.d.ts","sourceRoot":"","sources":["../src/server-analyzer.ts"],"names":[],"mappings":"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"}