docs(init): document the deliberate dual shape of init error payloads

Runtime-reported error payloads include a blank "requestId" (and
possibly an empty "stackTrace") on AWS, while platform-synthesized
payloads (Sandbox.Timedout, Runtime.ExitError) carry neither — both
validated by localstack-pro's AWS snapshots. Spell this out on
lsapi.ErrorResponse and adaptInitErrorPayload so the asymmetry between
the two ReportInitFailure paths is not mistaken for a bug and unified.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: joe4dev

cmd/localstack/custom_interop.go

@@ -287,7 +287,11 @@ func (c *CustomInteropServer) ReportInitFailure(errType fatalerror.ErrorType, me
 // adaptInitErrorPayload injects the requestId into the runtime's structured /init/error
 // payload, preserving all other fields exactly as the runtime emitted them — in particular an
 // empty but present "stackTrace": [] (e.g. Runtime.HandlerNotFound), which a typed struct with
-// omitempty would drop on re-marshal. AWS includes a (blank) requestId in init error payloads.
+// omitempty would drop on re-marshal.
+//
+// AWS includes a (blank) "requestId" in runtime-reported init error payloads but NOT in
+// platform-synthesized ones (e.g. Runtime.ExitError) — see the lsapi.ErrorResponse doc for the
+// AWS-snapshot evidence. The two ReportInitFailure paths intentionally differ in this regard.
 // Returns nil if the payload cannot be adapted (it is then forwarded unmodified).
 func adaptInitErrorPayload(payload []byte, requestID string) []byte {
 	var fields map[string]any

internal/lsapi/types.go

@@ -14,6 +14,15 @@ type LogResponse struct {
 }
 
 // ErrorResponse is sent to LocalStack when encountering an error.
+//
+// It is used for payloads the platform synthesizes itself (e.g. Sandbox.Timedout,
+// Runtime.ExitError). On AWS these carry no requestId/stackTrace fields — unlike
+// runtime-reported error payloads, which include a blank "requestId" and possibly an empty
+// "stackTrace" (validated against AWS in localstack-pro's test_lambda.py snapshots, e.g.
+// test_lambda_invoke_with_timeout and test_lambda_init_timeout_then_crash vs
+// test_lambda_handler_not_found). Runtime-reported payloads are therefore forwarded
+// verbatim (see adaptInitErrorPayload) rather than re-marshaled through this struct, and
+// the omitempty tags here are deliberate.
 type ErrorResponse struct {
 	ErrorMessage string   `json:"errorMessage"`
 	ErrorType    string   `json:"errorType,omitempty"`