declaration

type Block struct {
	Parameters []types.Type
	// ControlBoundary prevents return, break, and next from crossing a
	// backend callback whose target-language ownership would otherwise differ.
	// Nested functions and loops still own their local control transfers.
	ControlBoundary bool
	// Return makes the block value-producing. The final expression must be
	// assignable to this type.
	Return types.Type
	// ResultBoundary makes prefix try abort this structured operation with its
	// declared Result error. A value-producing block uses Return as the success
	// type; a structured iteration uses the enclosing member's Result success.
	// It is not an authored block parameter. Authored return is rejected until
	// lexical transfer and resource cleanup share one portable contract; use try
	// to abort this boundary with Err.
	ResultBoundary types.Type
	// Structured keeps the block in typed IR instead of lowering it to a
	// backend callback. Structured blocks may be assigned or returned while
	// preserving return, break, and next in their lexical owner.
	Structured bool
}

type Catalog struct {
	Types                          map[string]*Type
	Modules                        map[string]*Module
	FunctionBlockRules             []FunctionBlockRule
	FunctionArgumentReferenceRules []FunctionArgumentReferenceRule
	ClassBodyDeclarationRules      []ClassBodyDeclarationRule
	// RuntimeTypesByModule names compiler-owned value representations required
	// by generated declarations in a particular application module.
	RuntimeTypesByModule map[string][]types.Type
}

type ClassBodyDeclarationRule struct {
	Package  string
	Function string
	Owner    DeclarationReference
}

type DeclarationReference struct {
	ModulePath string
	Name       string
}

type FunctionArgumentReferenceRule struct {
	Package  string
	Function string
	Argument int
	Owner    DeclarationReference
	Targets  []DeclarationReference
}

type FunctionBlockRule struct {
	Package             string
	Function            string
	EnclosingSuperclass string
	TypeArgument        int
	ParameterTypeSuffix string
}

type Member struct {
	Name      string
	Kind      MemberKind
	Intrinsic string
	// Specializer identifies a package-extension call provider. The provider
	// receives resolved, serializable semantic facts and returns ordinary
	// TypeRB helper source plus a narrow call replacement.
	Specializer      string
	Parameters       []Parameter
	MinimumArguments int
	MaximumArguments int
	Return           types.Type
	Variadic         bool
	Class            bool
	TypeParameters   []string
	Provider         string
	Alternatives     []Signature
	Block            *Block
}

type MemberKind string

type Module struct {
	Name            string
	InstanceMembers map[string]Member
}

type Parameter struct {
	Name     string
	Type     types.Type
	Keyword  bool
	Optional bool
	// RepresentationBoundary accepts a source type when its runtime
	// representation is assignable to Type. Package providers use this only at
	// typed serialization or persistence boundaries; ordinary TypeRB calls keep
	// nominal newtypes distinct.
	RepresentationBoundary bool
	LiteralValues          []string
	LiteralArrays          [][]string
	LiteralArrayElements   []string
}

type Signature struct {
	Parameters []Parameter
	Return     types.Type
	Variadic   bool
}

type Type struct {
	Name           string
	TypeParameters []string
	Superclass     string
	// SourceModule identifies a provider declaration backed by a project
	// source type. Outside that module, ordinary source references still need
	// an explicit import even though provider members remain available after
	// the type flows through another declaration.
	SourceModule    string
	InstanceMembers map[string]Member
	ClassMembers    map[string]Member
}