Configuration

Engine configuration

shield.Config holds global defaults for the safety engine:

type Config struct {
    DefaultProfile     string        // safety profile to use when none specified
    ShutdownTimeout    time.Duration // graceful shutdown timeout (default: 30s)
    ScanConcurrency    int           // max parallel scans (default: 10)
    EnableShortCircuit bool          // skip deeper layers on block (default: true)
}

Defaults

shield.DefaultConfig() // returns:
// Config{
//     ShutdownTimeout:    30 * time.Second,
//     ScanConcurrency:    10,
//     EnableShortCircuit: true,
// }

Overriding defaults

Pass a custom config via engine options:

eng, err := engine.New(
    engine.WithConfig(shield.Config{
        DefaultProfile:     "strict",
        ScanConcurrency:    20,
        EnableShortCircuit: true,
    }),
    engine.WithStore(pgStore),
)

Engine options

Option	Description
`engine.WithStore(s)`	Sets the composite store
`engine.WithConfig(cfg)`	Sets the engine configuration
`engine.WithPlugin(p)`	Registers a lifecycle plugin
`engine.WithLogger(l)`	Sets the structured logger

Top-level Shield options

The root shield package provides options for composing safety primitives inline:

type Options struct {
    Config     Config
    Profile    string     // default safety profile name
    Instincts  []string   // inline instinct names
    Awareness  []string   // inline awareness detector names
    Values     []string   // inline value names
    Boundaries []string   // inline boundary names
    Judgments  []string   // inline judgment names
    Reflexes   []string   // inline reflex names
}

Option	Description
`shield.WithConfig(cfg)`	Sets the Shield configuration
`shield.WithProfile(name)`	Sets the default safety profile
`shield.WithInstincts(names...)`	Adds inline instinct names
`shield.WithAwareness(names...)`	Adds inline awareness detector names
`shield.WithValues(names...)`	Adds inline value names
`shield.WithBoundaries(names...)`	Adds inline boundary names
`shield.WithJudgments(names...)`	Adds inline judgment names
`shield.WithReflexes(names...)`	Adds inline reflex names

Forge extension options

The extension.New function accepts its own set of options:

ext := extension.New(
    extension.WithStore(pgStore),
    extension.WithPlugin(metricsPlugin),
    extension.WithDisableRoutes(),
    extension.WithDisableMigrate(),
    extension.WithBasePath("/shield"),
    extension.WithGroveDatabase(""),
)

Option	Type	Default	Description
`WithStore(s)`	`store.Store`	--	Composite store (auto-resolved from grove if not set).
`WithPlugin(p)`	`plugin.Plugin`	--	Lifecycle plugin (repeatable).
`WithEngineOption(opt)`	`engine.Option`	--	Pass-through engine option.
`WithConfig(cfg)`	`Config`	defaults	Full config struct.
`WithDisableRoutes()`	--	`false`	Skip HTTP route registration.
`WithDisableMigrate()`	--	`false`	Skip migrations on Start.
`WithBasePath(path)`	`string`	`""`	URL prefix for shield routes.
`WithGroveDatabase(name)`	`string`	`""`	Named grove.DB to resolve from DI.
`WithRequireConfig(b)`	`bool`	`false`	Require config in YAML files.

File-based configuration (YAML)

When running as a Forge extension, Shield automatically loads configuration from YAML config files. The extension looks for config under the following keys (in order):

extensions.shield -- standard Forge extension config namespace
shield -- top-level shorthand

Example

# forge.yaml
extensions:
  shield:
    disable_routes: false
    disable_migrate: false
    base_path: "/shield"
    default_profile: ""
    shutdown_timeout: "30s"
    scan_concurrency: 10
    enable_short_circuit: true
    grove_database: ""

Config fields

YAML Key	Type	Default	Description
`disable_routes`	`bool`	`false`	Skip HTTP route registration
`disable_migrate`	`bool`	`false`	Skip migrations on Start
`base_path`	`string`	`""`	URL prefix for all routes
`default_profile`	`string`	`""`	Safety profile when none specified
`shutdown_timeout`	`duration`	`"30s"`	Max graceful shutdown wait
`scan_concurrency`	`int`	`10`	Max parallel scan operations
`enable_short_circuit`	`bool`	`true`	Skip deeper layers on block decision
`grove_database`	`string`	`""`	Named grove.DB from DI

File-based configuration is merged with programmatic options. Programmatic boolean flags (DisableRoutes, DisableMigrate) always win when set to true. For other fields, YAML values take precedence, then programmatic values, then defaults.