core

func Application ¶

func Application() sdk.Definition

Application marks the package-level function that defines a Spice application target.

The function remains ordinary valid Go. Spice inspects its exact parameter types as application roots and never executes its body during analysis. Argument-free package-main markers compose same-module packages through explicit blank Go imports on the command package. The imported packages join the same typed compiler program; named imports and external side-effect imports retain ordinary Go semantics. Generated NewApplication, Start, Stop, and Run code owns construction, rollback, lifecycle ordering, and shutdown; no runtime reflection or global service locator is introduced.

Use one explicit import in every file that declares the marker:

// @import { Application } from "github.com/spice-framework/spice/annotation/core"
// @Application
func main() {}

func ApplicationHandler ¶

func ApplicationHandler(
	_ context.Context,
	invocation sdk.Invocation,
) (sdk.Result, error)

ApplicationHandler contributes application-marker semantics.

func Bean ¶

func Bean() sdk.Definition

Bean marks a provider function or a method on a @Configuration type.

Spice derives dependencies and output from exact Go type identity. A provider may additionally return lifecycle.Cleanup and error. Cleanup is registered immediately after construction and runs in reverse order during rollback or shutdown. Interface outputs require an explicit adapter provider; assignability is never guessed.

// @import { Bean } from "github.com/spice-framework/spice/annotation/core"
// @Bean
type StoreConfiguration struct{}

// @Bean
func (*StoreConfiguration) Store(config Config) (*Store, lifecycle.Cleanup, error)

func BeanHandler ¶

func BeanHandler(
	_ context.Context,
	invocation sdk.Invocation,
) (sdk.Result, error)

BeanHandler contributes exact-type provider semantics.

func Component ¶

func Component() sdk.Definition

Component declares a constructible generic managed bean.

Use Component when a managed type is not application-service logic, a data repository, an HTTP controller, or a configuration factory. Spice selects and calls an ordinary Go constructor directly; it does not scan packages or use reflection. Component supports the same bean identity, scope, ordering, selection, and explicit interface-binding annotations as Service.

// @import { Component } from "github.com/spice-framework/spice/annotation/core"
// @Component
type PasswordHasher struct{}

func NewPasswordHasher() *PasswordHasher

func ComponentHandler ¶

func ComponentHandler(
	_ context.Context,
	invocation sdk.Invocation,
) (sdk.Result, error)

ComponentHandler contributes generic component construction metadata.

func Configuration ¶

func Configuration() sdk.Definition

Configuration declares a constructible factory bean that owns @Bean methods.

A configuration type is constructed through the same direct compile-time constructor selection as Service and Component. Annotated methods are then invoked directly on that instance. Use @ConfigurationProperties for typed external configuration values.

// @import { Bean, Configuration } from "github.com/spice-framework/spice/annotation/core"
// @Configuration
type DatabaseConfiguration struct{}

// @Bean
func (*DatabaseConfiguration) Database(properties DatabaseProperties) (*sql.DB, error)

func ConfigurationHandler ¶

func ConfigurationHandler(
	_ context.Context,
	invocation sdk.Invocation,
) (sdk.Result, error)

ConfigurationHandler contributes configuration-factory construction metadata.

func ConfigurationProperties ¶

func ConfigurationProperties() sdk.Definition

ConfigurationProperties marks a struct as generated typed configuration.

Field metadata remains on ordinary Go struct tags. Spice derives stable keys, defaults, required values, secret redaction, validation, and generated metadata without reflecting over the application at runtime. Prefix is optional and must be dot-separated lowercase identifiers; each segment may contain single interior hyphens.

// @import { ConfigurationProperties } from "github.com/spice-framework/spice/annotation/core"
// @ConfigurationProperties(prefix="agent.runtime-plugin")
type RuntimePluginProperties struct {
	Limit int `spice:"limit,default=100"`
}

func ConfigurationPropertiesHandler ¶

func ConfigurationPropertiesHandler(
	_ context.Context,
	invocation sdk.Invocation,
) (sdk.Result, error)

ConfigurationPropertiesHandler contributes typed properties semantics.

func Enum ¶

func Enum() sdk.Definition

Enum declares that same-file constants form the complete legal value set of one named scalar type.

Spice validates enum structure and emits ordinary type-associated parsing, string, and validity helpers. It does not build a runtime reflection registry.

// @import { Enum } from "github.com/spice-framework/spice/annotation/core"
// @Enum
type OrderStatus string

const (
	OrderStatusPending   OrderStatus = "pending"
	OrderStatusCompleted OrderStatus = "completed"
)

func EnumHandler ¶

func EnumHandler(
	_ context.Context,
	invocation sdk.Invocation,
) (sdk.Result, error)

EnumHandler contributes closed-enum validation and generation intent.

func Fallback ¶

func Fallback() sdk.Definition

Fallback makes a bean eligible only when no non-fallback bean matches the requested exact type and qualifiers.

func FallbackHandler ¶

func FallbackHandler(
	_ context.Context,
	invocation sdk.Invocation,
) (sdk.Result, error)

FallbackHandler contributes fallback-selection metadata.

func Implements ¶

func Implements() sdk.Definition

Implements explicitly exposes a concrete Spice bean through one or more named Go interfaces.

Every argument is a typed Go interface expression resolved against the annotation's physical source file. Spice verifies the factory's exact result type in the compiler's shared go/types universe and emits the equivalent Go blank-identifier compile-time assertion in a manifest-owned source shard. The annotation never performs implicit assignability scanning: concrete injection uses the exact result type, while interface injection sees only explicit Implements bindings or factories that return the interface exactly.

// @import { Implements, Service } from "github.com/spice-framework/spice/annotation/core"
// @import * as payments from "example.com/commerce/payments"
// @import * as health from "example.com/commerce/health"
// @Service
// @Implements(payments.Processor, health.Checker)
type StripeProcessor struct{}

Generated code owns both compile-time assertions, calls the bean constructor directly, and relies on normal Go assignment to the interface parameter. No reflection, string lookup, global client, or runtime package scan is introduced.

func ImplementsHandler ¶

func ImplementsHandler(
	_ context.Context,
	invocation sdk.Invocation,
) (sdk.Result, error)

ImplementsHandler contributes explicit interface-binding expressions. The compiler resolves and verifies the expressions in its existing type universe.

func Order ¶

func Order() sdk.Definition

Order controls deterministic collection injection ordering. Lower values are injected first; equal values use bean name and source identity.

func OrderHandler ¶

func OrderHandler(
	_ context.Context,
	invocation sdk.Invocation,
) (sdk.Result, error)

OrderHandler contributes deterministic collection ordering metadata.

func Primary ¶

func Primary() sdk.Definition

Primary makes a bean the preferred candidate when multiple non-fallback beans match one exact dependency type.

func PrimaryHandler ¶

func PrimaryHandler(
	_ context.Context,
	invocation sdk.Invocation,
) (sdk.Result, error)

PrimaryHandler contributes primary-selection metadata.

func Prototype ¶

func Prototype() sdk.Definition

Prototype constructs a fresh bean for each generated provider acquisition. Its cleanup is returned to the caller and is never hidden in application shutdown.

func PrototypeHandler ¶

func PrototypeHandler(
	_ context.Context,
	invocation sdk.Invocation,
) (sdk.Result, error)

PrototypeHandler contributes caller-owned prototype scope metadata.

func Qualifier ¶

func Qualifier() sdk.Definition

Qualifier assigns a semantic selection name to a bean or requests that qualifier on one constructor parameter.

Qualifiers are explicit compile-time metadata. They never trigger runtime string lookup: the compiler resolves the selected declaration and generated Go passes its typed value directly.

// @Qualifier("stripe")
type StripeProcessor struct{}

func NewCheckout(
	// @Qualifier("stripe")
	processor payments.Processor,
) *Checkout

func QualifierHandler ¶

func QualifierHandler(
	_ context.Context,
	invocation sdk.Invocation,
) (sdk.Result, error)

QualifierHandler contributes one deterministic selection qualifier.

func Repository ¶

func Repository() sdk.Definition

Repository declares a constructible data-access bean.

Constructor discovery and dependency injection follow the same compile-time rules as Service. Repository is a semantic role for module ownership, transactions, diagnostics, navigation, and observability; generated code still contains only direct ordinary Go constructor calls.

// @import { Repository } from "github.com/spice-framework/spice/annotation/core"
// @Repository(constructor=NewOrderRepository)
type OrderRepository struct{}

func RepositoryHandler ¶

func RepositoryHandler(
	_ context.Context,
	invocation sdk.Invocation,
) (sdk.Result, error)

RepositoryHandler contributes explicit repository construction metadata.

func RequestScope ¶

func RequestScope() sdk.Definition

RequestScope constructs one bean per explicit request scope and assigns its cleanup to that scope.

func RequestScopeHandler ¶

func RequestScopeHandler(
	_ context.Context,
	invocation sdk.Invocation,
) (sdk.Result, error)

RequestScopeHandler contributes request-owned scope metadata.

func Service ¶

func Service() sdk.Definition

Service declares a constructible application-service bean.

Spice selects an ordinary Go constructor at compile time: an explicit constructor symbol, New<Type>, the unambiguous package New function, or generated new(T). Dependencies remain constructor parameters and generated code calls the selected constructor directly. No reflection or service locator is used. Use @Implements to expose the concrete result through an interface; Spice verifies it with a generated Go compile-time assertion.

// @import { Service } from "github.com/spice-framework/spice/annotation/core"
// @Service(constructor=NewOrders)
type Orders struct{}

func NewOrders(repository Repository) *Orders

func ServiceHandler ¶

func ServiceHandler(
	_ context.Context,
	invocation sdk.Invocation,
) (sdk.Result, error)

ServiceHandler contributes explicit service stereotype semantics.

func SessionScope ¶

func SessionScope() sdk.Definition

SessionScope constructs one bean per explicit session scope and assigns its cleanup to that scope.

func SessionScopeHandler ¶

func SessionScopeHandler(
	_ context.Context,
	invocation sdk.Invocation,
) (sdk.Result, error)

SessionScopeHandler contributes session-owned scope metadata.

func Singleton ¶

func Singleton() sdk.Definition

Singleton assigns the default application-owned scope explicitly.

func SingletonHandler ¶

func SingletonHandler(
	_ context.Context,
	invocation sdk.Invocation,
) (sdk.Result, error)

SingletonHandler contributes application-owned singleton scope metadata.