feat: add typed error system for executor

cmd/mxcli/docker/detect.go

@@ -13,10 +13,10 @@
 // CDN downloads are the primary source for mxbuild and runtime.
 //
 // Resolution priority (all platforms):
-//   1. Explicit path (--mxbuild-path)
-//   2. PATH lookup
-//   3. OS-specific known locations (Studio Pro on Windows)
-//   4. Cached CDN downloads (~/.mxcli/mxbuild/)
+//  1. Explicit path (--mxbuild-path)
+//  2. PATH lookup
+//  3. OS-specific known locations (Studio Pro on Windows)
+//  4. Cached CDN downloads (~/.mxcli/mxbuild/)
 //
 // Path discovery on Windows must NOT hardcode drive letters. Use environment
 // variables (PROGRAMFILES, PROGRAMW6432, SystemDrive) to locate install dirs.

mdl/ast/ast_entity.go

@@ -33,15 +33,15 @@ func (k EntityKind) String() string {
 
 // CreateEntityStmt represents: CREATE [OR MODIFY] PERSISTENT|NON-PERSISTENT ENTITY Module.Name [EXTENDS Parent] (attributes) ...
 type CreateEntityStmt struct {
-	Name             QualifiedName
-	Kind             EntityKind
-	Generalization   *QualifiedName    // Parent entity for inheritance (e.g., System.Image)
-	Attributes       []Attribute
-	Indexes          []Index
-	EventHandlers    []EventHandlerDef // ON BEFORE/AFTER CREATE/COMMIT/DELETE/ROLLBACK CALL ...
-	Position         *Position
-	Documentation    string
-	Comment          string
+	Name           QualifiedName
+	Kind           EntityKind
+	Generalization *QualifiedName // Parent entity for inheritance (e.g., System.Image)
+	Attributes     []Attribute
+	Indexes        []Index
+	EventHandlers  []EventHandlerDef // ON BEFORE/AFTER CREATE/COMMIT/DELETE/ROLLBACK CALL ...
+	Position       *Position
+	Documentation  string
+	Comment        string
 	CreateOrModify bool // true for CREATE OR MODIFY
 }
 
@@ -58,17 +58,17 @@ func (s *DropEntityStmt) isStatement() {}
 type AlterEntityOp int
 
 const (
-	AlterEntityAddAttribute      AlterEntityOp = iota // ADD ATTRIBUTE / ADD COLUMN
-	AlterEntityRenameAttribute                        // RENAME ATTRIBUTE / RENAME COLUMN
-	AlterEntityModifyAttribute                        // MODIFY ATTRIBUTE / MODIFY COLUMN
-	AlterEntityDropAttribute                          // DROP ATTRIBUTE / DROP COLUMN
-	AlterEntitySetDocumentation                       // SET DOCUMENTATION
-	AlterEntitySetComment                             // SET COMMENT
-	AlterEntityAddIndex                               // ADD INDEX
-	AlterEntityDropIndex                              // DROP INDEX
-	AlterEntitySetPosition // SET POSITION (x, y)
-	AlterEntityAddEventHandler                        // ADD EVENT HANDLER ON BEFORE/AFTER CREATE/COMMIT/DELETE/ROLLBACK CALL Mod.MF
-	AlterEntityDropEventHandler                       // DROP EVENT HANDLER ON BEFORE/AFTER CREATE/COMMIT/DELETE/ROLLBACK
+	AlterEntityAddAttribute     AlterEntityOp = iota // ADD ATTRIBUTE / ADD COLUMN
+	AlterEntityRenameAttribute                       // RENAME ATTRIBUTE / RENAME COLUMN
+	AlterEntityModifyAttribute                       // MODIFY ATTRIBUTE / MODIFY COLUMN
+	AlterEntityDropAttribute                         // DROP ATTRIBUTE / DROP COLUMN
+	AlterEntitySetDocumentation                      // SET DOCUMENTATION
+	AlterEntitySetComment                            // SET COMMENT
+	AlterEntityAddIndex                              // ADD INDEX
+	AlterEntityDropIndex                             // DROP INDEX
+	AlterEntitySetPosition                           // SET POSITION (x, y)
+	AlterEntityAddEventHandler                       // ADD EVENT HANDLER ON BEFORE/AFTER CREATE/COMMIT/DELETE/ROLLBACK CALL Mod.MF
+	AlterEntityDropEventHandler                      // DROP EVENT HANDLER ON BEFORE/AFTER CREATE/COMMIT/DELETE/ROLLBACK
 )
 
 // EventHandlerDef represents an event handler in CREATE/ALTER ENTITY syntax.
@@ -84,17 +84,17 @@ type EventHandlerDef struct {
 type AlterEntityStmt struct {
 	Name                QualifiedName
 	Operation           AlterEntityOp
-	Attribute           *Attribute     // For ADD ATTRIBUTE
-	AttributeName       string         // For RENAME/MODIFY/DROP ATTRIBUTE
-	NewName             string         // For RENAME ATTRIBUTE
-	DataType            DataType       // For MODIFY ATTRIBUTE
-	Calculated          bool           // For MODIFY ATTRIBUTE with CALCULATED
-	CalculatedMicroflow *QualifiedName // For MODIFY ATTRIBUTE with CALCULATED microflow
-	Documentation       string         // For SET DOCUMENTATION
-	Comment             string         // For SET COMMENT
-	Index               *Index         // For ADD INDEX
-	IndexName           string         // For DROP INDEX
-	Position            *Position      // For SET POSITION
+	Attribute           *Attribute       // For ADD ATTRIBUTE
+	AttributeName       string           // For RENAME/MODIFY/DROP ATTRIBUTE
+	NewName             string           // For RENAME ATTRIBUTE
+	DataType            DataType         // For MODIFY ATTRIBUTE
+	Calculated          bool             // For MODIFY ATTRIBUTE with CALCULATED
+	CalculatedMicroflow *QualifiedName   // For MODIFY ATTRIBUTE with CALCULATED microflow
+	Documentation       string           // For SET DOCUMENTATION
+	Comment             string           // For SET COMMENT
+	Index               *Index           // For ADD INDEX
+	IndexName           string           // For DROP INDEX
+	Position            *Position        // For SET POSITION
 	EventHandler        *EventHandlerDef // For ADD/DROP EVENT HANDLER
 }
 

mdl/ast/ast_microflow.go

@@ -657,11 +657,11 @@ func (s *ExportToMappingStmt) isMicroflowStatement() {}
 
 // TransformJsonStmt represents: $Result = TRANSFORM $Input WITH Module.Transformer
 type TransformJsonStmt struct {
-	OutputVariable  string               // Result string variable (without $)
-	InputVariable   string               // Source JSON string variable (without $)
-	Transformation  QualifiedName        // Data transformer qualified name
-	ErrorHandling   *ErrorHandlingClause // Optional ON ERROR clause
-	Annotations     *ActivityAnnotations // Optional @position, @caption, @color, @annotation
+	OutputVariable string               // Result string variable (without $)
+	InputVariable  string               // Source JSON string variable (without $)
+	Transformation QualifiedName        // Data transformer qualified name
+	ErrorHandling  *ErrorHandlingClause // Optional ON ERROR clause
+	Annotations    *ActivityAnnotations // Optional @position, @caption, @color, @annotation
 }
 
 func (s *TransformJsonStmt) isMicroflowStatement() {}

mdl/ast/ast_query.go

@@ -79,7 +79,7 @@ const (
 	ShowImageCollections      // SHOW IMAGE COLLECTIONS [IN module]
 	ShowRestClients           // SHOW REST CLIENTS [IN module]
 	ShowPublishedRestServices // SHOW PUBLISHED REST SERVICES [IN module]
-	ShowDataTransformers     // LIST DATA TRANSFORMERS [IN module]
+	ShowDataTransformers      // LIST DATA TRANSFORMERS [IN module]
 	ShowConstantValues        // SHOW CONSTANT VALUES [IN module]
 	ShowContractEntities      // SHOW CONTRACT ENTITIES FROM Module.Service
 	ShowContractActions       // SHOW CONTRACT ACTIONS FROM Module.Service

mdl/ast/ast_rest.go

@@ -32,15 +32,15 @@ type RestOperationDef struct {
 	Documentation    string
 	Method           string // "GET", "POST", "PUT", "PATCH", "DELETE"
 	Path             string
-	Parameters       []RestParamDef       // path parameters
-	QueryParameters  []RestParamDef       // query parameters
-	Headers          []RestHeaderDef      // HTTP headers
-	BodyType         string               // "JSON", "FILE", "TEMPLATE", "MAPPING", "" (none)
-	BodyVariable     string               // e.g. "$ItemData" or template string
-	BodyMapping      *RestMappingDef      // for MAPPING body
-	ResponseType     string               // "JSON", "STRING", "FILE", "STATUS", "NONE", "MAPPING"
-	ResponseVariable string               // e.g. "$CreatedItem"
-	ResponseMapping  *RestMappingDef      // for MAPPING response
+	Parameters       []RestParamDef  // path parameters
+	QueryParameters  []RestParamDef  // query parameters
+	Headers          []RestHeaderDef // HTTP headers
+	BodyType         string          // "JSON", "FILE", "TEMPLATE", "MAPPING", "" (none)
+	BodyVariable     string          // e.g. "$ItemData" or template string
+	BodyMapping      *RestMappingDef // for MAPPING body
+	ResponseType     string          // "JSON", "STRING", "FILE", "STATUS", "NONE", "MAPPING"
+	ResponseVariable string          // e.g. "$CreatedItem"
+	ResponseMapping  *RestMappingDef // for MAPPING response
 	Timeout          int
 }
 

mdl/errors/errors.go

@@ -0,0 +1,144 @@
+// SPDX-License-Identifier: Apache-2.0
+
+// Package mdlerrors provides structured error types for the MDL executor.
+//
+// Typed errors support errors.As for programmatic classification.
+// Sentinel or wrapped errors may also support errors.Is where applicable
+// (for example, ErrExit and BackendError via Unwrap).
+// Every error preserves the original message via Error() for backward-compatible
+// string output — callers that only use %v or .Error() see no change.
+//
+// Only BackendError supports Unwrap — it wraps an underlying storage/IO error.
+// All other error types are leaf errors with no wrapped cause.
+package mdlerrors
+
+import (
+	"errors"
+	"fmt"
+)
+
+// ErrExit is a sentinel error indicating clean script/session termination.
+// Use errors.Is(err, ErrExit) to detect exit requests.
+var ErrExit = errors.New("exit")
+
+// NotConnectedError indicates an operation was attempted without an active project connection.
+type NotConnectedError struct {
+	// WriteMode is true when write access was required but not available.
+	WriteMode bool
+	msg       string
+}
+
+// NewNotConnected creates a NotConnectedError for read access.
+func NewNotConnected() *NotConnectedError {
+	return &NotConnectedError{msg: "not connected to a project"}
+}
+
+// NewNotConnectedWrite creates a NotConnectedError for write access.
+func NewNotConnectedWrite() *NotConnectedError {
+	return &NotConnectedError{WriteMode: true, msg: "not connected to a project in write mode"}
+}
+
+func (e *NotConnectedError) Error() string { return e.msg }
+
+// NotFoundError indicates a named element was not found.
+type NotFoundError struct {
+	// Kind is the element type (e.g. "entity", "module", "microflow").
+	Kind string
+	// Name is the qualified or simple name of the element.
+	Name string
+	msg  string
+}
+
+// NewNotFound creates a NotFoundError.
+func NewNotFound(kind, name string) *NotFoundError {
+	return &NotFoundError{
+		Kind: kind,
+		Name: name,
+		msg:  fmt.Sprintf("%s not found: %s", kind, name),
+	}
+}
+
+// NewNotFoundMsg creates a NotFoundError with a custom message.
+func NewNotFoundMsg(kind, name, msg string) *NotFoundError {
+	return &NotFoundError{Kind: kind, Name: name, msg: msg}
+}
+
+func (e *NotFoundError) Error() string { return e.msg }
+
+// AlreadyExistsError indicates an element already exists when creating.
+type AlreadyExistsError struct {
+	// Kind is the element type.
+	Kind string
+	// Name is the qualified or simple name.
+	Name string
+	msg  string
+}
+
+// NewAlreadyExists creates an AlreadyExistsError.
+func NewAlreadyExists(kind, name string) *AlreadyExistsError {
+	return &AlreadyExistsError{
+		Kind: kind,
+		Name: name,
+		msg:  fmt.Sprintf("%s already exists: %s", kind, name),
+	}
+}
+
+// NewAlreadyExistsMsg creates an AlreadyExistsError with a custom message.
+func NewAlreadyExistsMsg(kind, name, msg string) *AlreadyExistsError {
+	return &AlreadyExistsError{Kind: kind, Name: name, msg: msg}
+}
+
+func (e *AlreadyExistsError) Error() string { return e.msg }
+
+// UnsupportedError indicates an unsupported operation, feature, or property.
+type UnsupportedError struct {
+	// What holds the full error message describing what is unsupported
+	// (e.g. "unsupported attribute type: Binary").
+	What string
+	msg  string
+}
+
+// NewUnsupported creates an UnsupportedError.
+func NewUnsupported(msg string) *UnsupportedError {
+	return &UnsupportedError{What: msg, msg: msg}
+}
+
+func (e *UnsupportedError) Error() string { return e.msg }
+
+// ValidationError indicates invalid input or configuration.
+type ValidationError struct {
+	msg string
+}
+
+// NewValidation creates a ValidationError.
+func NewValidation(msg string) *ValidationError {
+	return &ValidationError{msg: msg}
+}
+
+// NewValidationf creates a ValidationError with formatted message.
+func NewValidationf(format string, args ...any) *ValidationError {
+	return &ValidationError{msg: fmt.Sprintf(format, args...)}
+}
+
+func (e *ValidationError) Error() string { return e.msg }
+
+// BackendError wraps an error from the underlying storage layer (mpr/SDK).
+type BackendError struct {
+	// Op describes the operation that failed (e.g. "get domain model", "write entity").
+	Op  string
+	Err error
+}
+
+// NewBackend creates a BackendError wrapping a cause.
+func NewBackend(op string, err error) *BackendError {
+	return &BackendError{Op: op, Err: err}
+}
+
+func (e *BackendError) Error() string {
+	if e.Err == nil {
+		return fmt.Sprintf("failed to %s", e.Op)
+	}
+	return fmt.Sprintf("failed to %s: %v", e.Op, e.Err)
+}
+
+func (e *BackendError) Unwrap() error { return e.Err }