[hoegertn]

Closes #385.

What this does

Gives createAppSyncHandler typed-error support so expected resolver failures (forbidden, not-found, validation, conflict) surface as GraphQL errors without failing the Lambda invocation, keeping them off the Lambda Errors metric. The resolver-side support is opt-in so upgrading consumers see no change unless they ask for it.

Changes

• src/lambda/appsync-errors.ts (new): AppSyncError base carrying readonly errorType: string and optional errorInfo, with subclasses ForbiddenError (Forbidden), NotFoundError (NotFound), ValidationError (ValidationError), ConflictError (Conflict). Re-exported from errors.ts as a nested namespace, so consumers use errors.appsync.* and the existing HTTP errors.ForbiddenError / errors.NotFoundError are unchanged.
• src/lambda/handler.ts: on catching an AppSyncError, createAppSyncHandler logs at warn and returns a sentinel-stamped envelope ({ __appSyncError: true, data: null, errorType, errorMessage, errorInfo }) instead of rethrowing. Untyped errors still log at error and rethrow.
• src/constructs/graphql.ts: new API-wide typedErrors?: boolean prop on GraphQlApiProps (@default false). When unset, addLambdaResolver synthesizes the pre-createAppSyncHandler: support typed errors so expected failures return GraphQL errors without failing the Lambda invocation #385 plain UNIT direct-Lambda resolver, so upgrading consumers get zero resolver-topology diff. When true, it synthesizes an APPSYNC_JS pipeline resolver whose response handler converts the envelope into a GraphQL error via util.error(message, errorType, null, errorInfo).
• Tests: test/lambda/appsync-handler.test.ts (handler behavior) and test/constructs/graphql.test.ts (both the default UNIT path and the opt-in PIPELINE path).
• llm.md: documents the opt-in, that the default is unchanged UNIT resolvers (no cdk diff surprise), and the handler/pipeline matched-pair interaction.
• docs/experiments/appsync-unit-resolver-error-probe.md: a standalone probe spec used to settle, against a live AppSync API, that a bare UNIT direct-Lambda resolver cannot surface the typed-error envelope on a single Invoke. The probe confirmed the pipeline is required, which is why the opt-in path uses APPSYNC_JS.

Why opt-in

A live AppSync probe confirmed that a UNIT direct-Lambda resolver returns the { errorType, errorMessage } object as field data on a single Invoke rather than mapping it to a GraphQL error. Typed errors therefore require the APPSYNC_JS pipeline, which is a resolver-topology change. Gating it behind typedErrors means consumers who upgrade without opting in keep plain UNIT resolvers and see no cdk diff. Enabling typedErrors updates resolvers in place (logical IDs unchanged) and adds one FunctionConfiguration per Lambda resolver; run cdk diff after enabling.

Compatibility

Additive and backward compatible. Default behavior matches pre-#385 byte-for-byte (verified against commit e868b6a). The typedErrors flag applies to all Lambda resolvers on an API.

Verification

pnpm run build, pnpm run test (128 pass), pnpm run eslint clean, npx projen zero drift.

Handler/resolver coupling (enforced, not just documented)

createAppSyncHandler returns the sentinel envelope only when process.env.APPSYNC_TYPED_ERRORS === 'true', otherwise it rethrows the typed error (invocation fails loudly, same as pre-#385). addLambdaResolver injects APPSYNC_TYPED_ERRORS=true into the resolver Lambda only on the typedErrors: true pipeline path, the same path that attaches the response handler that can translate the envelope. This closes a regression where a handler throwing errors.appsync.* on the default UNIT path would return the raw envelope as field data with the error type silently dropped. Default when the env var is absent is rethrow, so hand-wired handlers used without GraphQlApi stay safe and must set APPSYNC_TYPED_ERRORS=true themselves to get envelope behavior.

Auth / HTTP errors on the AppSync path

createAppSyncHandler also translates HTTP errors (errors.HttpError and subclasses) into typed GraphQL errors, routed through the same APPSYNC_TYPED_ERRORS gate. This covers the errors the shared authorizer in src/lambda/auth.ts throws from assertAuthenticated / assertGroup / assertAdmin, which are expected permission failures on the AppSync path but were previously rethrown as untyped faults. Status-to-errorType mapping: 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, any other Error. auth.ts, the HTTP errors.* classes, and createHttpHandler are unchanged; the translation happens only at the AppSync boundary. Same rethrow-when-not-activated rule applies, so a default UNIT resolver whose handler hits an auth assertion still fails loudly unless typedErrors is active.