component

package
v0.1.0-alpha.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 27 Imported by: 0

README

Component Package

The component model every SemEngine component builds on: factory registration, immutable port declarations, typed ports, configuration schemas, and the lifecycle interface.

import "github.com/c360studio/semengine/component"

Overview

A component is one self-describing unit of a SemEngine process. There are five kinds: inputs (data sources), processors (data transformers), outputs (data sinks), storage (persistence), and gateways (query surfaces). Each one reports its ports, its health, and its data flow through the Discoverable interface. Its configuration schema, description and version are not reported by the component: they live in its factory's Registration, the one place a tool reads them (ListFactories).

The terms this README uses:

  • Factory: a function that builds a component from its raw JSON configuration and a Dependencies value. It decodes the configuration and does no I/O; the component's I/O starts in Start.
  • Port declarer: a function, registered beside the factory, that derives the component's ports from the same raw configuration without building anything. It lets a tool read a component's ports offline.
  • Declaration: the immutable port shape of one component instance (its name, factory, ports, and the resources it holds exclusively). The Registry keeps declarations, never the live component.
  • Boot admission: building each configured instance once at process start, checking that the ports the component reports equal the ports its declarer derives, and recording its declaration.
  • Sealing: closing boot admission. After SealComposition, the Registry refuses to create or admit another component until the process starts again with a new Registry.
  • Component manager: service.ComponentManager, which owns every live component and its lifecycle: it builds each configured instance once, starts the set (store providers first) and stops it in reverse start order.

Registration

A component package exports a Register(registry) function instead of registering itself in init(). That function makes one registry.Register(component.Registration{...}) call per factory. The host creates a Registry, calls each package's Register, and hands the registry to the component manager. The manager calls CreateComponent for each enabled instance and then SealComposition.

Explicit registration keeps package imports free of side effects: a test builds a registry holding only the components it needs, and the host decides what is registered and in which order. The cost is that a new component package must be added to the host's list of Register calls.

Implementing a component

package mycomponent

import (
    "encoding/json"

    "github.com/c360studio/semengine/component"
)

// Config is this component's configuration; its factory decodes it.
type Config struct {
    Subject string `json:"subject"`
}

var schema = component.ConfigSchema{
    Properties: map[string]component.PropertySchema{
        "subject": {Type: "string", Description: "NATS subject the input publishes on"},
    },
    Required: []string{"subject"},
}

// outputPorts derives the ports from the configuration. The port declarer and
// the component both call it, so the declared and the reported ports agree.
func outputPorts(cfg Config) []component.Port {
    return []component.Port{{
        Name:      "output",
        Direction: component.DirectionOutput,
        Required:  true,
        Config:    component.NATSPort{Subject: cfg.Subject},
    }}
}

// declarePorts is the port declarer: no dependencies, no I/O.
func declarePorts(raw json.RawMessage, _ string) (component.PortConfig, error) {
    var cfg Config
    if err := component.SafeUnmarshal(raw, &cfg); err != nil {
        return component.PortConfig{}, err
    }
    return component.PortConfigFrom(nil, outputPorts(cfg)), nil
}

type Input struct {
    cfg  Config
    deps component.Dependencies
}

func (c *Input) InputPorts() []component.Port    { return nil }
func (c *Input) OutputPorts() []component.Port   { return outputPorts(c.cfg) }
func (c *Input) Health() component.HealthStatus  { return component.HealthStatus{Healthy: true} }
func (c *Input) DataFlow() component.FlowMetrics { return component.FlowMetrics{} }

// create is the factory.
func create(raw json.RawMessage, deps component.Dependencies) (component.Discoverable, error) {
    var cfg Config
    if err := component.SafeUnmarshal(raw, &cfg); err != nil {
        return nil, err
    }
    return &Input{cfg: cfg, deps: deps}, nil
}

// Register adds this package's factory to a registry. The host calls it.
// The registration is the one home of the schema, description and version.
func Register(registry *component.Registry) error {
    return registry.Register(component.Registration{
        Name:        "my-input",
        Factory:     create,
        Ports:       declarePorts,
        Schema:      schema,
        Type:        "input",
        Protocol:    "nats",
        Domain:      "example",
        Description: "Example input",
        Version:     "1.0.0",
    })
}

A component that does work also implements LifecycleComponent: Initialize() error, Start(ctx) error and Stop(ctx) error beside Discoverable. Start and Stop refuse a nil context, and Stop joins the work Start began. AsLifecycleComponent reports whether a Discoverable implements it.

Lifecycle: the part every component shares

Writing that contract out for each component is repetitive and easy to get wrong, so component.Lifecycle implements it once. (ADR-108 calls this the processor shell.) A component holds a Lifecycle as an unexported field and answers LifecycleComponent and Discoverable's Health and DataFlow with one-line calls to it:

  • Initialize() marks the shell initialized and returns nil every time, with no I/O. Start before Initialize is refused.
  • Start(ctx, start, cleanup) admits one Start. A failed start is rolled back through cleanup; a cleanup that fails stays for the next Stop.
  • Stop(ctx) runs cleanup. It is safe before Start and safe to repeat.
  • Health(stuck...) reports stopped when not running, running and healthy when running, and degraded with the stuck states joined by "; " when running with any.
  • DataFlow() reports the counted inputs, their rates while running, and the time of the last one.
  • CountInput(bytes) and CountError() add one input of that many bytes, or one error, to the counts.

The shell is running from the moment start returns nil until cleanup begins. Health and DataFlow may be called at any time and never wait for a Start or Stop in progress. An error count never makes Health unhealthy; only a stuck state does.

The component keeps the rest. Its start acquires its resources and creates the run context for its continuing work (ending the context given to Start must stop nothing, ADR-113); its cleanup releases them in its own order, ends that run context, and joins the work within Stop's context. It decides which stuck states exist and passes them to each Health call. It registers its own metrics, validates its configuration at construction, and, if it has a DebugStatus, makes sure that does not wait for Start or Stop. The shell holds no context and no cancel function.

type sensor struct {
    lifecycle       component.Lifecycle
    calibrationLost atomic.Bool // the sensor's one stuck state
    // ... the run context's cancel function and the worker's done channel
}

func (s *sensor) Initialize() error               { return s.lifecycle.Initialize() }
func (s *sensor) Start(ctx context.Context) error { return s.lifecycle.Start(ctx, s.start, s.cleanup) }
func (s *sensor) Stop(ctx context.Context) error  { return s.lifecycle.Stop(ctx) }
func (s *sensor) DataFlow() component.FlowMetrics { return s.lifecycle.DataFlow() }
func (s *sensor) Health() component.HealthStatus  {
    if s.calibrationLost.Load() {
        return s.lifecycle.Health("calibration lost")
    }
    return s.lifecycle.Health()
}

// receive is what the sensor's subscription calls for each reading.
func (s *sensor) receive(payload []byte) { s.lifecycle.CountInput(len(payload)) }

start and cleanup are the sensor's own functions; the complete, runnable version, with both written out, is ExampleLifecycle in lifecycle_example_test.go. component.Lifecycle is framework API, offered to products built on SemEngine: that example calls it as a product would, and lifecycle_type_test.go proves each rule above, including that a component whose start runs its work under the Start context fails the lifecycle suite (internal/harness/lifecycletest).

FlowMetrics carries two totals beside the rates: Messages, the input messages counted since construction, and Bytes, their payload bytes. DataFlow reports them whether or not the component is running; the component manager serves them as data_flow.messages and data_flow.bytes.

core Concepts

Discoverable Interface

Every component implements four methods:

type Discoverable interface {
    InputPorts() []Port    // input port definitions
    OutputPorts() []Port   // output port definitions
    Health() HealthStatus  // current health status
    DataFlow() FlowMetrics // data flow metrics
}

A component's name, type, configuration schema, description and version are not methods: the name is the instance's and the rest is in its factory's Registration.

Dependencies

What the host passes to every factory:

type Dependencies struct {
    NATSClient      *natsclient.Client        // required: CreateComponent refuses a nil client
    MetricsRegistry *metric.MetricsRegistry   // may be nil
    Logger          *slog.Logger              // may be nil; GetLogger falls back to slog.Default()
    Platform        types.PlatformMeta        // the deployment's organization and platform
    Security        security.Config           // platform-wide security configuration
    ModelRegistry   model.RegistryReader      // the model registry chosen at boot; may be nil
    PayloadRegistry *payloadregistry.Registry // may be nil; a component that decodes BaseMessage needs it
    StoreRegistry   *storeregistry.Registry   // the stores storage components provide, filled by the manager
}

Dependencies carries no lifecycle manager and no tool registry. A component that needs the lifecycle manager (pkg/lifecycle) receives it from the host when it is registered or constructed. A contract test (internal/harness/contract/componentdeps_test.go) fails if component comes to import, directly or through another package, an agentic package, graph or a package under it, internal/graphmutation, pkg/lifecycle, or pkg/projection other than pkg/projection/contract.

Ports

A Port has a name, a direction, and a typed configuration (Config) that says what the port binds to:

// Core NATS publish or subscribe
component.NATSPort{Subject: "data.output"}

// JetStream stream and its subjects
component.JetStreamPort{StreamName: "EVENTS", Subjects: []string{"events.>"}}

// KV bucket watch; no keys means every key
component.KVWatchPort{Bucket: "CONFIG", Keys: []string{"app.*"}}

// KV bucket write, with the payload type it writes
component.KVWritePort{
    Bucket:    "ENTITY_STATES",
    Interface: &component.InterfaceContract{Type: "graph.EntityState", Version: "v1"},
}

// Network listener
component.NetworkPort{Protocol: "udp", Host: "0.0.0.0", Port: 14550}

The other port types are NATSRequestPort (request and reply), KVReadPort, HTTPClientPort, FilePort, TimerPort, StoreReadPort and StoreProvidePort, each in a port_*.go file.

Registry

  • NewRegistry() returns an empty registry.
  • Register(Registration) registers a factory and its static metadata under Registration.Name, and keeps its own copy: a later change to the caller's value, its schema or its dependency list changes nothing registered. The one exception is a schema default (PropertySchema.Default) that is not a JSON value: the registry copies nil, a string, a bool, a number, a []string, and a []any or map[string]any holding these at any depth; a default of any other type is stored as is, so a pointer, slice or map it holds stays shared with the caller. It refuses a name ValidateComponentName refuses, a nil factory, a nil port declarer (Ports), a Type that is not one of the five types.ComponentType constants (types.ComponentType.Validate), and a name already registered.
  • ListFactories() returns a copy of each registration's metadata, without its factory function; it returns no live component.
  • Declare(instanceName, config) runs a factory's port declarer for one configured instance and returns its Declaration, without building the component. It refuses a component two of whose own network claims clash. Two NetworkPort claims clash when they have the same transport (UDP for the protocol udp in any letter case, TCP for every other protocol) and the same port, and either host is a wildcard (an unspecified address such as 0.0.0.0 or ::), or both hosts are IP addresses naming one address (::ffff:127.0.0.1 names 127.0.0.1, and an IPv6 zone is ignored, so ::1%lo0 names ::1), or both hosts are the same text. Host names are not resolved: localhost beside 127.0.0.1 is admitted, and the bind at Start decides it. The refusal is of the invalid class and reads resource conflict: component 'gateway' claims ws:0.0.0.0:8080, held by another of its ports as http:0.0.0.0:8080, naming the later claim (inputs first, then outputs) and the earlier one.
  • CreateComponent(instanceName, config, deps, prepare), SealComposition() and Snapshots() exist for the component manager. Snapshots() returns a copy of every admitted Declaration, sorted by instance name; changing one changes nothing in the registry. A consumer creates and composes components through that manager; a direct call is not refused, but it bypasses the manager's bookkeeping. CreateComponent refuses a disabled instance, a nil Dependencies.NATSClient, a port declaration that differs from the ports the built component reports, an instance name already admitted, a network claim that clashes with one another instance holds or with another of its own (the rule under Declare), and any call after SealComposition. A refusal between components reads resource conflict: component 'second' claims tcp:127.0.0.1:8080, held by component 'first' as tcp:0.0.0.0:8080, naming the first holder in instance-name order when several clash. prepare may be nil.
Decoding a configuration

SafeUnmarshal(rawConfig, target) is offered to component factories and port declarers to decode their configuration. It checks, in this order, and refuses with an error of the invalid class:

  1. The target: nil, a nil pointer, or a value that is not a pointer.
  2. The configuration, through ValidateFactoryConfig: its size, nesting depth, array length, string and key length, control characters, numbers a float64 cannot hold, and anything but whitespace after the first JSON value. CreateComponent and Declare run the same check before a factory or declarer sees the configuration.
  3. The decode: a key the target struct does not define (the error names the key), a value of the wrong type, or data after the first value.

An empty configuration returns at once: it leaves the target's defaults and does not call Validate, so a factory whose defaults need checking checks them itself. After a nonempty configuration decodes, if the target implements Validatable, its Validate runs last; its error is returned wrapped, keeping whatever class it carries.

Types
Factory
type Factory func(rawConfig json.RawMessage, deps Dependencies) (Discoverable, error)

Factory function signature for component creation.

Errors

Every refusal from Register is a pkg/errs error of the invalid class, and its message names the factory:

err := registry.Register(registration)
if errs.IsInvalid(err) {
    // The name, factory, port declarer or type is refused, or the name is already registered.
}

CreateComponent wraps a factory's own error with errs.Wrap, so its class is the one the factory chose.

Concurrency

Every Registry method is safe for concurrent use; one read-write mutex guards the factories, the declarations and the sealed flag. A factory and a port declarer run without that mutex held. Sealing stops CreateComponent; it does not stop Register.

Testing

  • Build a registry per test with NewRegistry() and register only the components the test needs; no registry is process-global.
  • A test in this module that needs NATS opens a server through internal/harness/natsfixture (natsfixture.Open).
  • Test a component through its Discoverable and LifecycleComponent methods, not its private fields.

Architecture Decisions

Explicit Registration vs init()

Decision: Use explicit Register() functions

Rationale:

  • Testability: Can create isolated registries without global state
  • Explicitness: Clear component dependency graph in the host's list of Register calls
  • Control: Application controls what gets registered and when
  • No side effects: Package imports don't modify global state
  • Deterministic: Registration order is explicit and controllable

Tradeoffs:

  • Requires the host to keep a list of Register calls
  • Registration must be explicitly called in main()
  • New components must be added to the host's list of Register calls
Dependency Injection via Struct

Decision: Use Dependencies struct

Rationale:

  • Avoids parameter proliferation
  • Easy to add dependencies without breaking factories
  • Enables testing with mock dependencies
  • Follows service architecture patterns
Factory Pattern

Decision: Components parse their own configuration

Rationale:

  • Enables flexible validation per component
  • Matches service constructor patterns
  • Centralizes configuration knowledge in component packages

componentregistry (a host's list of Register calls) is not yet in SemEngine; each host writes its own.

Documentation

Overview

Package component defines the Discoverable interface and related types

Package component defines SemEngine component factories, lifecycle interfaces, dependencies, configuration schemas, ports, and immutable registry declarations.

Applications register component factories explicitly during process composition, one Registry.Register call per factory. The Registration is the one home of a factory's configuration schema, description and version. Factories are side-effect free: they construct a Discoverable, while I/O begins in Start and all owned work joins Stop.

Component creation is a boot operation of the component manager (service.ComponentManager). It constructs every enabled component from its constructor-captured configuration, captures the component's declared ports and resources, and admits an immutable declaration to Registry. The manager retains the concrete handle as the sole lifecycle owner. Registry does not refuse a direct call; such a call bypasses the manager's bookkeeping.

Registry read surfaces return defensive values and never expose a live component handle: Snapshots returns a copy of each admitted Declaration. Once boot admission is complete, Registry is sealed; later component admission attempts fail until another process boot creates a fresh Registry.

Discoverable components report their typed ports, health and flow metrics. Dependencies.Platform is the deployment's types.PlatformMeta. Port declarations support core NATS subjects, JetStream, KV watches and writes, request/reply, network listeners, APIs, and related framework patterns. Registry.Declare produces the same declaration values offline, for static diagram validation, without constructing a component.

Package component provides port configuration and management for component connections.

Package component provides schema tag parsing and generation for component configuration.

The schema tag system eliminates duplication between Config structs and ConfigSchema definitions by auto-generating schemas from struct tags. This provides a single source of truth for configuration metadata and follows Go stdlib patterns (similar to json tags).

Basic Usage

Define configuration with schema tags:

type MyConfig struct {
    Name string `json:"name" schema:"type:string,description:Component name,category:basic"`
    Port int    `json:"port" schema:"type:int,description:Port,min:1,max:65535,default:8080"`
}

Generate schema at init time:

var schema = component.GenerateConfigSchema(reflect.TypeOf(MyConfig{}))

Tag Syntax

Tags use comma-separated directives with colon-separated key-value pairs:

  • type:string - Field data type (required)
  • description:text - Field description (recommended)
  • category:basic - UI organization (basic or advanced)
  • default:value - Default value
  • min:N, max:N - Numeric constraints
  • enum:a|b|c - Valid enum values (pipe-separated)
  • readonly, editable - Boolean flags for PortDefinition fields
  • required, hidden - Boolean flags for validation and UI

Performance

Schema generation uses reflection but is designed for init-time execution:

  • Call GenerateConfigSchema once at package init
  • Cache result in package-level variable
  • Zero reflection cost at runtime

Error Handling

ParseSchemaTag returns an error for an invalid tag. The schema generators panic on one, naming the struct type, the field and the tag: every schema is built once from constant struct tags, so a bad tag is a programming error, as a bad pattern is to regexp.MustCompile. Missing descriptions use field names as fallback.

See docs/architecture/SCHEMA_TAG_SPEC.md for complete specification.

Index

Examples

Constants

View Source
const (
	MaxStringLength = 1024        // Maximum length for string values
	MaxJSONSize     = 1024 * 1024 // Maximum JSON size (1MB)
)

Config validation constants - security limits

View Source
const (
	// DepModelRegistry states that a component consumes
	// Dependencies.ModelRegistry at construction or run time, the model
	// registry selected at boot. Later model_registry writes require process
	// restart.
	DepModelRegistry = "model-registry"
)

Dependency identifiers used by Registration.Dependencies. Components declare these at registration to state which boot dependencies they consume; nothing reads the declaration, and every component receives Dependencies.ModelRegistry, the registry selected at boot. Kept as typed constants so refactors are compiler-checked.

Variables

This section is empty.

Functions

func GenerateCacheFieldSchema

func GenerateCacheFieldSchema() map[string]CacheFieldInfo

GenerateCacheFieldSchema generates metadata for cache.Config fields. This describes which fields in cache.Config are editable and their constraints, enabling the UI to render appropriate controls for cache configuration.

The function examines cache.Config struct tags to determine:

  • Field types (for appropriate UI controls)
  • Editability (whether users can modify the field)
  • Enum values (for strategy field)
  • Numeric constraints (for size limits)

All cache.Config fields are marked as "editable" to allow runtime configuration.

This metadata is included in ConfigSchema for fields with type "cache", allowing the frontend to correctly render cache configuration forms.

Returns:

  • Map of field names to CacheFieldInfo with type, editability, and constraint metadata

func GeneratePortFieldSchema

func GeneratePortFieldSchema() map[string]PortFieldInfo

GeneratePortFieldSchema returns the canonical common-envelope metadata. Kind-specific data remains inside config and is validated by the closed port binding table; schema generation does not reflect retired flat fields.

This metadata is included in ConfigSchema for fields with type "ports", allowing the frontend to correctly render port configuration forms.

Returns:

  • Map of field names to PortFieldInfo with type and editability metadata

func ResolveSubject

func ResolveSubject(ports []PortDefinition, portName, suffix string) (string, error)

ResolveSubject returns the configured NATS subject for one uniquely named port with a trailing wildcard replaced by suffix.

func SafeUnmarshal

func SafeUnmarshal(rawConfig json.RawMessage, target any) error

SafeUnmarshal decodes a component configuration into target, a non-nil pointer. It checks, in order: the target (nil, a nil pointer or a non-pointer is refused), the configuration (ValidateFactoryConfig), then decodes strictly, refusing a key the target does not define and data after the first value. Empty input returns at once, leaving the target's defaults and without calling Validate. After nonempty input decodes, a target that implements Validatable is validated last. Every refusal but Validate's own error is of the invalid class.

func ValidateComponentName

func ValidateComponentName(name string) error

ValidateComponentName validates component/instance names for security

func ValidateFactoryConfig

func ValidateFactoryConfig(rawConfig json.RawMessage) error

ValidateFactoryConfig performs validation before passing to factory This is the main security gate for all component configurations

Types

type CacheFieldInfo

type CacheFieldInfo struct {
	Type     string   `json:"type"`
	Editable bool     `json:"editable"`
	Enum     []string `json:"enum,omitempty"` // For strategy field
	Min      *int     `json:"min,omitempty"`  // For numeric fields
}

CacheFieldInfo describes metadata for cache.Config fields

type ConfigSchema

type ConfigSchema struct {
	Properties map[string]PropertySchema `json:"properties"`
	Required   []string                  `json:"required"`
}

ConfigSchema describes the configuration parameters for a component

func GenerateConfigSchema

func GenerateConfigSchema(configType reflect.Type) ConfigSchema

GenerateConfigSchema generates a ConfigSchema from a struct type using reflection. This function performs one-time reflection at initialization to extract schema metadata from struct field tags, eliminating the need for manual schema definitions.

Usage Pattern:

type MyComponentConfig struct {
    Name string `json:"name" schema:"type:string,description:Name,category:basic"`
    Port int    `json:"port" schema:"type:int,description:Port,min:1,max:65535"`
}

var schema = component.GenerateConfigSchema(reflect.TypeOf(MyComponentConfig{}))

Field Processing:

  • Only exported fields with both 'json' and 'schema' tags are included
  • json:"-" fields are skipped
  • Fields without schema tags are skipped
  • An invalid schema tag panics, naming the struct type, the field and the tag

Special Handling:

  • Fields with type "ports" automatically include PortFieldSchema metadata
  • Default values are converted from strings to appropriate types
  • Required fields are added to the schema's Required list

Performance:

  • Call once at init() time - reflection cost is paid only once
  • Generated schemas are cached in package-level variables
  • Zero reflection overhead at runtime

Parameters:

  • configType: The reflect.Type of the config struct (use reflect.TypeOf(ConfigStruct{})) Pointer types are automatically dereferenced

Returns:

  • ConfigSchema with Properties map and Required list populated from struct tags
  • Empty schema for non-struct types
Example

ExampleGenerateConfigSchema demonstrates how to use schema tags to auto-generate configuration schemas from struct definitions

package main

import (
	"encoding/json"
	"fmt"
	"reflect"

	"github.com/c360studio/semengine/component"
)

func main() {
	// Define a configuration struct with schema tags
	type ComponentConfig struct {
		// Basic configuration
		Name    string `json:"name"    schema:"type:string,description:Component name,category:basic"`
		Port    int    `json:"port"    schema:"type:int,description:Listen port,min:1,max:65535,default:8080,category:basic"`
		Enabled bool   `json:"enabled" schema:"type:bool,description:Enable component,default:true,category:basic"`

		// Advanced configuration
		Timeout  string `json:"timeout"   schema:"type:string,description:Request timeout,default:30s,category:advanced"`
		LogLevel string `json:"log_level" schema:"type:enum,description:Logging level,enum:debug|info|warn|error,default:info,category:advanced"`

		// Required field
		APIKey string `json:"api_key" schema:"required,type:string,description:Authentication API key"`
	}

	// Generate the schema at init time (one-time reflection cost)
	schema := component.GenerateConfigSchema(reflect.TypeOf(ComponentConfig{}))

	// The generated schema can be used for validation, UI generation, etc.
	schemaJSON, _ := json.MarshalIndent(schema, "", "  ")
	fmt.Println(string(schemaJSON))

	// Output will show the generated schema with all properties
}

type ConfigValidator

type ConfigValidator struct {
	// contains filtered or unexported fields
}

ConfigValidator provides secure validation for component configurations

func NewConfigValidator

func NewConfigValidator() *ConfigValidator

NewConfigValidator creates a validator with secure defaults

func (*ConfigValidator) ValidateConfig

func (v *ConfigValidator) ValidateConfig(rawConfig json.RawMessage) error

ValidateConfig performs comprehensive validation on raw JSON config This prevents injection attacks, resource exhaustion, and malformed input

type ConsumerConfig

type ConsumerConfig struct {
	DeliverPolicy     string
	AckPolicy         string
	MaxDeliver        int
	AckWait           time.Duration
	HeartbeatInterval time.Duration
	MaxAckPending     int // 0 = inherited/default/capped server policy; -1 = unlimited outstanding acks
}

ConsumerConfig holds extracted JetStream consumer configuration.

Duration fields (AckWait, HeartbeatInterval) are zero-valued when the port-level string is empty; consumers may apply their component default. Invalid declarations are rejected before a ConsumerConfig is returned.

func GetConsumerConfig

func GetConsumerConfig(port Port) (ConsumerConfig, error)

GetConsumerConfig validates a JetStream port through the canonical facts projection and extracts its consumer configuration. A non-JetStream or invalid port returns an error rather than silently receiving defaults. Unset fields receive these defaults: - DeliverPolicy: "new" (safe default - don't replay historical messages) - AckPolicy: "explicit" - MaxDeliver: 3 - AckWait, HeartbeatInterval: zero (caller applies per-component default)

type DebugStatusProvider

type DebugStatusProvider interface {
	// DebugStatus returns extended debug information for the component.
	// The returned value should be JSON-serializable.
	DebugStatus() any
}

DebugStatusProvider is an optional interface for components that can provide extended debug information beyond basic health status.

type Declaration

type Declaration struct {
	InstanceName    string
	FactoryIdentity string
	ComponentType   types.ComponentType
	InputPorts      []Port
	OutputPorts     []Port
	InputFacts      []PortFacts
	OutputFacts     []PortFacts
}

Declaration is the immutable port shape of one component instance: what the Registry retains for an admitted component, and what Declare produces for a configured-but-unconstructed one. It carries no lifecycle, health, readiness, grouping, or orchestration state. InputFacts[i] describes InputPorts[i] and OutputFacts[i] describes OutputPorts[i]: both lists of each pair come from one projection, so readers take them by index together.

func (Declaration) ConflictWith

func (d Declaration) ConflictWith(held Declaration) error

ConflictWith returns nil when no exclusive claim of d clashes with an exclusive claim of held, under the rule admission applies. Otherwise it returns a plain error naming the first clash: held's claims are visited in turn and, for each, d's, each side inputs first, then outputs, in declaration order. CreateComponent refuses a candidate with this error, so an offline check that calls it reports what admission would.

type Dependencies

type Dependencies struct {
	NATSClient      *natsclient.Client        // NATS client for messaging
	MetricsRegistry *metric.MetricsRegistry   // Metrics registry for Prometheus (can be nil)
	Logger          *slog.Logger              // Structured logger (can be nil, defaults to slog.Default())
	Platform        types.PlatformMeta        // Platform identity (organization and platform)
	Security        security.Config           // Platform-wide security configuration
	ModelRegistry   model.RegistryReader      // Boot-selected model registry (can be nil)
	PayloadRegistry *payloadregistry.Registry // Shared payload registry (can be nil; components unmarshaling BaseMessage require it)

	// StoreRegistry is the shared {StorageInstance → storage.StreamableStore}
	// resolver (ADR-063). The ComponentManager populates it from the boot-composed
	// storage components' store-provide ports at Start and clears entries at Stop;
	// content-fetch consumers (graph-embedding, fusion) resolve a StorageRef's
	// StorageInstance through it, lazily per-fetch. Concrete framework-leaf type
	// per the PayloadRegistry precedent.
	//
	// Can be nil — deployments with no offloaded-content fetch pay zero cost. A
	// consumer that receives a StorageReference without this exact-name authority
	// reports content-unresolved and excludes the body; it never selects another
	// store or degrades solely because the name is unresolved.
	StoreRegistry *storeregistry.Registry
}

Dependencies provides all external dependencies needed by components.

It carries no lifecycle manager and no tool registry. A component that needs the lifecycle manager receives it from its host when it is registered or constructed, so importing component reaches no graph or agentic package.

PayloadRegistry uses the concrete *payloadregistry.Registry rather than an interface on purpose: payloadregistry is a leaf package this package already imports, so there's no cycle to dodge, and message.NewDecoder also requires the concrete type. An interface here would force callers to type-assert at every Decoder construction site — pure friction for no abstraction win.

func (*Dependencies) GetLogger

func (d *Dependencies) GetLogger() *slog.Logger

GetLogger returns the configured logger or a default logger if none is provided

func (*Dependencies) GetLoggerWithComponent

func (d *Dependencies) GetLoggerWithComponent(componentName string) *slog.Logger

GetLoggerWithComponent returns a logger configured with component context

type Direction

type Direction string

Direction identifies whether data enters or leaves a component.

const (
	DirectionInput  Direction = "input"
	DirectionOutput Direction = "output"
)

Direction constants for port data flow.

type Discoverable

type Discoverable interface {
	// InputPorts returns the ports this component accepts data on
	InputPorts() []Port

	// OutputPorts returns the ports this component produces data on
	OutputPorts() []Port

	// Health returns current health status
	Health() HealthStatus

	// DataFlow returns current data flow metrics
	DataFlow() FlowMetrics
}

Discoverable defines the interface for components that can be discovered and inspected by the management layer. This interface enables dynamic discovery of component capabilities, configuration, and health status.

Components implementing this interface can be: - Input components: Accept external data (UDP, TCP, HTTP) - Processor components: Transform data (plugins) - Output components: Send data to external systems - Storage components: Store and retrieve data (ObjectStore, KV)

type Factory

type Factory func(rawConfig json.RawMessage, deps Dependencies) (Discoverable, error)

Factory creates a component instance from configuration following service pattern The factory function receives raw JSON configuration and dependencies, parses its own config, and returns a properly initialized component that implements the Discoverable interface. All I/O operations should be performed in the component's Start() method, not in the factory. This pattern matches service constructors: func(rawConfig json.RawMessage, deps Dependencies) (Service, error)

type FilePort

type FilePort struct {
	Path    string `json:"path"`
	Pattern string `json:"pattern,omitempty"`
}

FilePort - File system access

func (FilePort) IsExclusive

func (f FilePort) IsExclusive() bool

IsExclusive returns false as multiple components can read files

func (FilePort) Kind

func (f FilePort) Kind() PortKind

Kind returns the canonical port kind.

func (FilePort) ResourceID

func (f FilePort) ResourceID() string

ResourceID returns unique identifier for file ports

type FlowMetrics

type FlowMetrics struct {
	MessagesPerSecond float64   `json:"messages_per_second"`
	BytesPerSecond    float64   `json:"bytes_per_second"`
	ErrorRate         float64   `json:"error_rate"`
	LastActivity      time.Time `json:"last_activity"`
	Messages          int64     `json:"messages"` // input messages counted since construction
	Bytes             int64     `json:"bytes"`    // their payload bytes
}

FlowMetrics describes the current data flow through a component

type HTTPClientPort

type HTTPClientPort struct {
	Method        string             `json:"method,omitempty"`         // Required HTTP method
	URLPattern    string             `json:"url_pattern"`              // target endpoint/resource pattern; NO inline creds, NO query-string secrets
	TriggerPort   string             `json:"trigger_port,omitempty"`   // NAME of a sibling TimerPort driving cadence (empty = event-driven/internal)
	AuthRef       string             `json:"auth_ref,omitempty"`       // credential key name resolved at runtime; NEVER a secret value; empty = unauthenticated
	ContactPolicy string             `json:"contact_policy,omitempty"` // public User-Agent/contact identity (feeds often require it); not a secret
	Interface     *InterfaceContract `json:"interface,omitempty"`      // message-interface contract this port produces
}

HTTPClientPort describes an outbound HTTP-client / polling input dependency: a relationship where the component initiates connections to an external HTTP resource (REST API, alert feed, snapshot endpoint) rather than binding a listener (NetworkPort) or consuming a NATS subject (NATSPort).

It is a DESCRIPTOR, not a runtime — like TimerPort it declares the dependency shape so lifecycle/config/health/flowgraph/ownership/telemetry tooling can SEE it; the polling/HTTP execution stays in the component. Cadence is NOT owned here: when polling is timer-driven the component also declares a TimerPort and this port references it by name via TriggerPort (single source of truth for the interval).

Secrets never appear in this descriptor. AuthRef carries a credential REFERENCE (a key name resolved at runtime from the component's secret source), never a value. No field holds a secret.

func (HTTPClientPort) IsExclusive

func (h HTTPClientPort) IsExclusive() bool

IsExclusive returns false: an outbound client relationship is shareable (multiple components may poll the same endpoint), unlike a NetworkPort listener.

func (HTTPClientPort) Kind

func (h HTTPClientPort) Kind() PortKind

Kind returns the canonical port kind.

func (HTTPClientPort) ResourceID

func (h HTTPClientPort) ResourceID() string

ResourceID returns a unique identifier for the HTTP client dependency. Two ports with the same method and URL pattern identify the same external resource.

type HealthStatus

type HealthStatus struct {
	Healthy    bool          `json:"healthy"`
	LastCheck  time.Time     `json:"last_check"`
	ErrorCount int           `json:"error_count"`
	LastError  string        `json:"last_error,omitempty"`
	Uptime     time.Duration `json:"uptime"`
	Status     string        `json:"status"`
}

HealthStatus describes the current health state of a component

type InteractionPattern

type InteractionPattern string

InteractionPattern is the canonical communication behavior of a resolved port.

const (
	PatternTimer      InteractionPattern = "timer"
	PatternNetwork    InteractionPattern = "network"
	PatternHTTPClient InteractionPattern = "http-client"
	PatternStream     InteractionPattern = "stream"
	PatternRequest    InteractionPattern = "request"
	PatternWatch      InteractionPattern = "watch"
	PatternRead       InteractionPattern = "read"
	PatternStore      InteractionPattern = "store"
)

Canonical interaction patterns projected from resolved ports.

type InterfaceContract

type InterfaceContract struct {
	Type       string   `json:"type"`
	Version    string   `json:"version,omitempty"`
	Compatible []string `json:"compatible,omitempty"`
}

InterfaceContract defines the payload contract carried across a port.

type JetStreamPort

type JetStreamPort struct {
	// Stream configuration (for outputs)
	StreamName      string   `json:"stream_name"`              // e.g., "ENTITY_EVENTS"
	Subjects        []string `json:"subjects"`                 // e.g., ["events.graph.entity.>"]
	Storage         string   `json:"storage,omitempty"`        // "file" or "memory" when declared
	RetentionPolicy string   `json:"retention,omitempty"`      // "limits", "interest", or "work_queue" when declared
	RetentionDays   int      `json:"retention_days,omitempty"` // Declared message retention in days
	MaxSizeGB       int      `json:"max_size_gb,omitempty"`    // Declared maximum stream size in GiB
	Replicas        int      `json:"replicas,omitempty"`       // Declared replica count

	// Consumer configuration (for inputs)
	ConsumerName  string `json:"consumer_name,omitempty"`  // Durable consumer name
	DeliverPolicy string `json:"deliver_policy,omitempty"` // Declared delivery policy
	AckPolicy     string `json:"ack_policy,omitempty"`     // Declared acknowledgement policy
	MaxDeliver    int    `json:"max_deliver,omitempty"`    // Declared maximum redelivery attempts
	// AckWait is the duration the JetStream server waits for an ack before
	// redelivering. Strings are parsed via time.ParseDuration ("90s",
	// "2m", "5m"). Empty falls through to a per-component default. The
	// component-level default is a starting point; this port-level field
	// lets operators tune ack_wait for long-running consumers (LLM model
	// calls, slow tool execution) without forking the component. Per
	// docs/operations/14-timeout-chain.md: ack_wait must comfortably
	// exceed the longest legitimate per-task wallclock budget so that
	// healthy long-tail work isn't reaped before it can ack.
	AckWait string `json:"ack_wait,omitempty"`
	// HeartbeatInterval is the cadence at which the consumer goroutine
	// fires msg.InProgress() to reset the ack clock. Strings are parsed
	// via time.ParseDuration ("60s", "90s"). Empty falls through to a
	// per-component default. Typed delivery owners require it to be at most
	// half the shortest positive BackOff interval, or half the effective AckWait
	// (an explicit positive value or the 30s server default) when BackOff is
	// empty, so one missed heartbeat does not trigger redelivery. Honored by
	// heartbeat-enabled typed consumers; pure-ack consumers ignore it. New
	// integrations use natsclient.ConsumeDeliveryWithHeartbeat.
	HeartbeatInterval string `json:"heartbeat_interval,omitempty"`
	// MaxAckPending caps the number of delivered-but-unacked messages the
	// server keeps in flight for this consumer — the consumer-side backpressure
	// lever. Empty/0 leaves policy to NATS, which may inherit a stream limit,
	// apply its default, or cap it under server/account policy; -1 is unlimited
	// outstanding acknowledgements. It is the operator's way to tune ingest
	// backpressure.
	MaxAckPending int `json:"max_ack_pending,omitempty"`

	// Import declares this INPUT port an import lane: the operator states that
	// entities arriving here were minted by a PEER deployment, so graph-ingest
	// accepts a foreign org.platform on it and refuses a subject claiming this
	// deployment's own pair (ADR-102 decision 5). Absent or false is the ordinary lane,
	// where the deployment's own authority is required — the fail-closed
	// default, so an operator who declares nothing imports nothing. It is a
	// statement of trust, not a value the operator computes: the framework
	// already holds the local pair and compares against it. Nothing on the wire
	// is authenticated; the recorded provenance is this declaration plus the
	// envelope `source` string. Meaningless on an output port and ignored
	// there.
	Import bool `json:"import,omitempty"`

	// Interface contract
	Interface *InterfaceContract `json:"interface,omitempty"`
}

JetStreamPort - NATS JetStream for durable, at-least-once messaging

func (JetStreamPort) IsExclusive

func (j JetStreamPort) IsExclusive() bool

IsExclusive returns false as JetStream manages consumer coordination

func (JetStreamPort) Kind

func (j JetStreamPort) Kind() PortKind

Kind returns the canonical port kind.

func (JetStreamPort) ResourceID

func (j JetStreamPort) ResourceID() string

ResourceID returns unique identifier for JetStream ports

type KVReadPort

type KVReadPort struct {
	Bucket    string             `json:"bucket"`
	Interface *InterfaceContract `json:"interface,omitempty"`
}

KVReadPort declares exact or list access to current values in one KV bucket. It is metadata only: acquisition and missing-value policy remain component-owned.

func (KVReadPort) IsExclusive

func (k KVReadPort) IsExclusive() bool

IsExclusive reports that concurrent readers may share a bucket.

func (KVReadPort) Kind

func (k KVReadPort) Kind() PortKind

Kind returns the canonical port kind.

func (KVReadPort) ResourceID

func (k KVReadPort) ResourceID() string

ResourceID returns the canonical KV read resource identity.

type KVWatchPort

type KVWatchPort struct {
	Bucket    string             `json:"bucket"`            // e.g., "ENTITY_STATES"
	Keys      []string           `json:"keys,omitempty"`    // Keys to watch, empty = all
	History   bool               `json:"history,omitempty"` // Include historical values
	Interface *InterfaceContract `json:"interface,omitempty"`
}

KVWatchPort - NATS KV Watch for state observation

func (KVWatchPort) IsExclusive

func (k KVWatchPort) IsExclusive() bool

IsExclusive returns false as multiple watchers are allowed

func (KVWatchPort) Kind

func (k KVWatchPort) Kind() PortKind

Kind returns the canonical port kind.

func (KVWatchPort) ResourceID

func (k KVWatchPort) ResourceID() string

ResourceID returns unique identifier for KV watch ports

type KVWritePort

type KVWritePort struct {
	Bucket    string             `json:"bucket"`              // e.g., "ENTITY_STATES"
	Interface *InterfaceContract `json:"interface,omitempty"` // Data type contract
}

KVWritePort - NATS KV Write for state persistence

func (KVWritePort) IsExclusive

func (k KVWritePort) IsExclusive() bool

IsExclusive returns false as multiple writers are allowed (with CAS handling)

func (KVWritePort) Kind

func (k KVWritePort) Kind() PortKind

Kind returns the canonical port kind.

func (KVWritePort) ResourceID

func (k KVWritePort) ResourceID() string

ResourceID returns unique identifier for KV write ports

type Lifecycle

type Lifecycle struct {
	// contains filtered or unexported fields
}

Lifecycle is the processor shell of ADR-108: the part of a component that is the same for every component, which is starting once, stopping, rolling back a failed start, and answering Health and DataFlow. A LifecycleComponent holds a Lifecycle as an unexported field and answers the lifecycle half of that interface with one-line calls to it.

The component supplies what only it knows: a start function that acquires its resources and creates the run context for its continuing work, a cleanup function that releases them in its own order and ends that run context (ADR-113), and its current stuck states at each Health call. The shell holds no context and no cancel and creates neither, decides no release order, reports no readiness and registers no metrics: its counters are plain integers.

The zero value is a shell that has not been initialized. A Lifecycle must not be copied after first use.

Example
package main

import (
	"context"
	"fmt"
	"sync"
	"sync/atomic"
	"time"

	"github.com/c360studio/semengine/component"
)

// sensor is a component as an outside author writes one: it holds a component.Lifecycle and
// gives it the two functions only the sensor knows, start and cleanup, and its stuck state at
// each Health read.
type sensor struct {
	lifecycle component.Lifecycle
	// calibrationLost is the sensor's one stuck state.
	calibrationLost atomic.Bool

	mu     sync.Mutex
	cancel context.CancelFunc
	done   chan struct{}
}

var _ component.LifecycleComponent = (*sensor)(nil)

func (s *sensor) Initialize() error               { return s.lifecycle.Initialize() }
func (s *sensor) Start(ctx context.Context) error { return s.lifecycle.Start(ctx, s.start, s.cleanup) }
func (s *sensor) Stop(ctx context.Context) error  { return s.lifecycle.Stop(ctx) }
func (s *sensor) Health() component.HealthStatus  { return s.lifecycle.Health(s.stuck()) }
func (s *sensor) DataFlow() component.FlowMetrics { return s.lifecycle.DataFlow() }

func (s *sensor) InputPorts() []component.Port  { return nil }
func (s *sensor) OutputPorts() []component.Port { return nil }

// start creates the run context for the sensor's continuing work (ADR-113): ending Start's
// context after Start returned stops nothing.
func (s *sensor) start(ctx context.Context) error {
	runCtx, cancel := context.WithCancel(context.WithoutCancel(ctx))
	done := make(chan struct{})
	go func() {
		defer close(done)
		<-runCtx.Done() // the sensor's polling loop would run here
	}()
	s.mu.Lock()
	s.cancel, s.done = cancel, done
	s.mu.Unlock()
	return nil
}

// cleanup ends the run context and joins the worker within Stop's bound.
func (s *sensor) cleanup(ctx context.Context) error {
	s.mu.Lock()
	cancel, done := s.cancel, s.done
	s.mu.Unlock()
	if cancel == nil {
		return nil
	}
	cancel()
	select {
	case <-done:
		return nil
	case <-ctx.Done():
		return ctx.Err()
	}
}

// receive is what the sensor's subscription calls for each reading.
func (s *sensor) receive(payload []byte) {
	s.lifecycle.CountInput(len(payload))
}

func (s *sensor) stuck() string {
	if s.calibrationLost.Load() {
		return "calibration lost"
	}
	return ""
}

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	s := &sensor{}
	if err := s.Initialize(); err != nil {
		fmt.Println("initialize:", err)
		return
	}
	if err := s.Start(ctx); err != nil {
		fmt.Println("start:", err)
		return
	}
	s.receive([]byte("21.5"))
	s.receive([]byte("21.7"))
	fmt.Println(s.Health().Status, s.DataFlow().Messages, s.DataFlow().Bytes)

	s.calibrationLost.Store(true)
	h := s.Health()
	fmt.Println(h.Status, h.LastError)

	if err := s.Stop(ctx); err != nil {
		fmt.Println("stop:", err)
		return
	}
	fmt.Println(s.Health().Status, s.DataFlow().Messages)
}
Output:
running 2 8
degraded calibration lost
stopped 2

func (*Lifecycle) CountError

func (l *Lifecycle) CountError()

CountError counts one processing error, reported as Health's ErrorCount and in DataFlow's ErrorRate.

func (*Lifecycle) CountInput

func (l *Lifecycle) CountInput(bytes int)

CountInput counts one input message of the given payload bytes and records its time as the last activity.

func (*Lifecycle) DataFlow

func (l *Lifecycle) DataFlow() FlowMetrics

DataFlow reports the CountInput totals since construction, running or not, and LastActivity, the time of the last CountInput or the zero time before the first. While running it also reports the totals per second of uptime and, once an input was counted, the counted errors per input; otherwise those rates are zero. DataFlow may be called at any time and never waits for Start or Stop.

func (*Lifecycle) Health

func (l *Lifecycle) Health(stuck ...string) HealthStatus

Health reports whether the shell is running and the stuck states the component passes in. Not running: Healthy false, Status "stopped", no LastError and zero Uptime, whatever stuck holds. Running with no stuck state: Healthy true and Status "running". Running with stuck states: Healthy false, Status "degraded" and LastError the states joined by "; ". An empty string is not a stuck state and is ignored. ErrorCount is the number of CountError calls and never lowers Healthy (ADR-109, Decision 2). Health may be called at any time and never waits for Start or Stop.

func (*Lifecycle) Initialize

func (l *Lifecycle) Initialize() error

Initialize marks the shell initialized and returns nil, every time. It does no I/O; it returns an error only so a component's Initialize can be the one line that calls it.

func (*Lifecycle) Start

func (l *Lifecycle) Start(ctx context.Context, start, cleanup func(context.Context) error) error

Start refuses a shell that was never initialized, running nothing, so a Start after Initialize is still admitted. Otherwise it is lifecycleguard's Start: a nil or ended context and a second Start are refused; start runs under ctx; a start that fails or panics is rolled back through cleanup, and a rollback that fails stays pending for the next Stop. The shell is running from the moment start returns nil until cleanup begins.

cleanup runs after a partial start as well as a complete one, so it must tolerate handles that were never acquired. It must not panic: a cleanup that panics leaves the guard's state behind it, so a later Stop cannot try again. The shell inherits that limitation from internal/lifecycleguard.

func (*Lifecycle) Stop

func (l *Lifecycle) Stop(ctx context.Context) error

Stop is lifecycleguard's Stop: it runs the cleanup Start was given even when ctx has already ended (clearing running status before cleanup begins) so teardown always initiates and ctx bounds only waits. Stop before Start returns nil and uses up the shell, a Stop after a successful cleanup is a no-op, a synchronous nil cleanup under an ended ctx marks the shell terminal while returning ctx.Err(), and a cleanup that fails stays pending for the next Stop.

type LifecycleComponent

type LifecycleComponent interface {
	Discoverable
	Initialize() error
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
}

LifecycleComponent is a component its host initializes, starts and stops. A caller can rely on these outcomes (ADR-108, Decision 3):

  • Start and Stop refuse a nil context, and Start refuses a context that has already ended.
  • Stop before Start is safe.
  • Start(ctx) does its startup work under ctx and returns once the component is ready; if ctx ends first, Start returns that error and holds nothing. Ending ctx after Start returned stops nothing: the component runs its continuing work under a context of its own, which Stop ends (ADR-113).
  • Stop(ctx) is the only stop. It drains, joins and cleans up within ctx's bound and returns nil only once everything is released; if ctx ends first, it returns that context's error and a later Stop tries again.
  • A repeated Stop is a no-op once an earlier Stop's cleanup succeeded; after a failed cleanup, what is left stays pending for a later Stop.
  • A second Start is refused. An instance never restarts; a host that needs the component again creates a new one.
  • A failed Start holds nothing, or, when its own cleanup also fails, it returns both errors and a later Stop releases what it left.
  • Configuration is validated once, at construction, and Initialize is idempotent and does no I/O.

Concurrent lifecycle calls are not part of the contract. Reads are: Health, DataFlow and DebugStatus may be called at any time, during Start or Stop and after Stop, and return without waiting for either; after Stop they report what the component knows then. Callers do so without waiting for Stop: the component manager's health and status routes, its health publisher (which ends only after the components have stopped) and the service manager's /readyz. The rule is tested for graph-ingest (TestGraphIngestHealthAndDataFlowAnswerDuringAndAfterStop) and is review only for components outside this module.

component.Lifecycle implements these rules for a component that holds one: nil contexts refused, ended Start contexts refused, Stop before Start safe, Stop initiating cleanup even when its context has already ended, one Start and no restart, a repeated Stop a no-op, a failed Start rolled back and a failed cleanup kept for the next Stop, Start refused before Initialize, Initialize idempotent with no I/O, and Health and DataFlow answering at any time without waiting. The component keeps the rest: its start creates the run context for its continuing work and its cleanup ends it, drains and joins that work within Stop's context and tolerates a partial start; it validates its configuration at construction; and its DebugStatus, if it has one, must not wait for Start or Stop.

func AsLifecycleComponent

func AsLifecycleComponent(comp Discoverable) (LifecycleComponent, bool)

AsLifecycleComponent safely casts a component to LifecycleComponent

type ManagedComponent

type ManagedComponent struct {
	// Component is the actual component instance
	Component Discoverable

	// State tracks the current lifecycle state
	State State

	// Config is the boot configuration this instance was created from. The
	// component set and each component's configuration are fixed at
	// construction, so it never changes for the life of the instance.
	Config types.ComponentConfig

	// StartOrder tracks the order components were started for reverse shutdown
	StartOrder int

	// LastError tracks the last error that occurred during lifecycle operations
	LastError error
}

ManagedComponent tracks a component and its lifecycle state This is used by ComponentManager to properly manage component lifecycle

type NATSPort

type NATSPort struct {
	Subject   string             `json:"subject"`
	Queue     string             `json:"queue,omitempty"`
	Interface *InterfaceContract `json:"interface,omitempty"`
}

NATSPort - NATS pub/sub

func (NATSPort) IsExclusive

func (n NATSPort) IsExclusive() bool

IsExclusive returns false as multiple components can subscribe

func (NATSPort) Kind

func (n NATSPort) Kind() PortKind

Kind returns the canonical port kind.

func (NATSPort) ResourceID

func (n NATSPort) ResourceID() string

ResourceID returns unique identifier for NATS ports

type NATSRequestPort

type NATSRequestPort struct {
	Subject   string             `json:"subject"`
	Timeout   string             `json:"timeout,omitempty"` // Duration string e.g. "1s", "500ms"
	Retries   int                `json:"retries,omitempty"`
	Interface *InterfaceContract `json:"interface,omitempty"`
}

NATSRequestPort - NATS Request/Response pattern for synchronous operations

func (NATSRequestPort) IsExclusive

func (n NATSRequestPort) IsExclusive() bool

IsExclusive returns false as multiple components can handle requests

func (NATSRequestPort) Kind

func (n NATSRequestPort) Kind() PortKind

Kind returns the canonical port kind.

func (NATSRequestPort) ResourceID

func (n NATSRequestPort) ResourceID() string

ResourceID returns unique identifier for NATS request ports

type NetworkFacts

type NetworkFacts struct {
	// contains filtered or unexported fields
}

NetworkFacts is the immutable listener binding portion of PortFacts.

func (NetworkFacts) Host

func (f NetworkFacts) Host() string

Host returns the configured bind host.

func (NetworkFacts) Port

func (f NetworkFacts) Port() int

Port returns the configured bind port.

func (NetworkFacts) Protocol

func (f NetworkFacts) Protocol() string

Protocol returns the network protocol.

type NetworkPort

type NetworkPort struct {
	Protocol string `json:"protocol"` // "udp" in any letter case is UDP; any other label ("tcp", "http") is TCP
	Host     string `json:"host"`     // "0.0.0.0", "localhost"
	Port     int    `json:"port"`     // 14550, 8080
}

NetworkPort - TCP/UDP network bindings

func (NetworkPort) IsExclusive

func (n NetworkPort) IsExclusive() bool

IsExclusive returns true as network ports are exclusive

func (NetworkPort) Kind

func (n NetworkPort) Kind() PortKind

Kind returns the canonical port kind.

func (NetworkPort) ResourceID

func (n NetworkPort) ResourceID() string

ResourceID returns unique identifier for network ports

type Port

type Port struct {
	Name        string    `json:"name"`
	Direction   Direction `json:"direction"`
	Required    bool      `json:"required,omitempty"`
	Description string    `json:"description,omitempty"`
	External    bool      `json:"external,omitempty"` // fed from outside the composition; see PortDefinition.External
	Config      Portable  `json:"config"`
}

Port is a resolved component I/O declaration.

func (Port) Facts

func (p Port) Facts() (PortFacts, error)

Facts revalidates the current Port value and returns its immutable semantic projection.

func (Port) MarshalJSON

func (p Port) MarshalJSON() ([]byte, error)

MarshalJSON encodes Port with the same config.kind envelope as PortDefinition.

func (*Port) UnmarshalJSON

func (p *Port) UnmarshalJSON(data []byte) error

UnmarshalJSON strictly decodes and resolves a runtime port.

type PortConfig

type PortConfig struct {
	Inputs  []PortDefinition `json:"inputs,omitempty"`
	Outputs []PortDefinition `json:"outputs,omitempty"`
}

PortConfig groups semantic declarations by data-flow direction.

func PortConfigFrom

func PortConfigFrom(inputs, outputs []Port) PortConfig

PortConfigFrom returns the configuration-shaped declaration of already resolved ports: the inverse of resolving a PortConfig lane by lane. Factories whose constructor resolves ports use it to expose the same ports as their PortDeclarer without a second derivation.

func (*PortConfig) UnmarshalJSON

func (p *PortConfig) UnmarshalJSON(data []byte) error

UnmarshalJSON rejects unknown top-level lanes such as the retired kv_write lane.

type PortDeclarer

type PortDeclarer func(rawConfig json.RawMessage, instanceName string) (PortConfig, error)

PortDeclarer declares a factory's ports as a pure function of the raw component configuration and the instance name. It takes no dependencies, performs no I/O, and constructs nothing: it is the static fact a registration carries beside Schema, evaluated offline by composition validation and verified against the constructed component at boot admission. The constructor MUST derive its ports from the same function so the two cannot drift.

type PortDefinition

type PortDefinition struct {
	Name        string `json:"name" schema:"readonly,type:string,description:Port identifier"`
	Required    bool   `json:"required,omitempty" schema:"readonly,type:bool,description:Whether port connection is required"`
	Description string `json:"description,omitempty" schema:"readonly,type:string,description:Human-readable port description"`
	// External declares that this input is fed from outside the composition
	// — a UI, a peer process, a rule action — so no publisher in the
	// composition's graph is expected. It is an operator statement, not a
	// predicted framework value: composition validation suppresses only the
	// no-publisher orphan finding for this port and nothing else (ADR-100).
	// Meaningful on inputs.
	External bool     `` /* 142-byte string literal not displayed */
	Config   Portable `json:"config" schema:"editable,type:object,description:Typed semantic port configuration"`
}

PortDefinition is a configuration-shaped semantic port declaration.

func (PortDefinition) MarshalJSON

func (p PortDefinition) MarshalJSON() ([]byte, error)

MarshalJSON writes the canonical common port envelope.

func (PortDefinition) Resolve

func (d PortDefinition) Resolve(direction Direction) (Port, error)

Resolve validates and resolves a configuration declaration for one direction.

func (*PortDefinition) UnmarshalJSON

func (p *PortDefinition) UnmarshalJSON(data []byte) error

UnmarshalJSON strictly decodes the canonical common port envelope.

type PortFacts

type PortFacts struct {
	// contains filtered or unexported fields
}

PortFacts is an immutable semantic projection of one resolved Port.

func (PortFacts) ConnectionIDs

func (f PortFacts) ConnectionIDs() []string

ConnectionIDs returns defensive copies of the identifiers used for flow matching.

func (PortFacts) InteractionPattern

func (f PortFacts) InteractionPattern() InteractionPattern

InteractionPattern returns the canonical communication behavior.

func (PortFacts) Interface

func (f PortFacts) Interface() (InterfaceContract, bool)

Interface returns a defensive copy of the semantic interface contract.

func (PortFacts) IsExclusive

func (f PortFacts) IsExclusive() bool

IsExclusive reports whether two ports may claim the same resource.

func (PortFacts) Kind

func (f PortFacts) Kind() PortKind

Kind returns the canonical port kind.

func (PortFacts) NATSSubjects

func (f PortFacts) NATSSubjects() []string

NATSSubjects returns defensive copies of declared NATS subject families.

func (PortFacts) Network

func (f PortFacts) Network() (NetworkFacts, bool)

Network returns the immutable network binding when the port declares one.

func (PortFacts) ResourceID

func (f PortFacts) ResourceID() string

ResourceID returns the canonical resource identity.

func (PortFacts) StoreReadBucket

func (f PortFacts) StoreReadBucket() (string, bool)

StoreReadBucket returns the configured content-store bucket for a store-read port.

func (PortFacts) Stream

func (f PortFacts) Stream() (StreamFacts, bool)

Stream returns the immutable JetStream projection when the port declares one.

type PortFieldInfo

type PortFieldInfo struct {
	Type                 string                   `json:"type"`
	Editable             bool                     `json:"editable"`
	Minimum              *int                     `json:"minimum,omitempty"`
	Enum                 []string                 `json:"enum,omitempty"`
	Required             []string                 `json:"required,omitempty"`
	AnyRequired          [][]string               `json:"anyRequired,omitempty"`
	RequiredByDirection  map[Direction][]string   `json:"requiredByDirection,omitempty"`
	Directions           []Direction              `json:"directions,omitempty"`
	Properties           map[string]PortFieldInfo `json:"properties,omitempty"`
	Variants             map[string]PortFieldInfo `json:"variants,omitempty"`
	Items                *PortFieldInfo           `json:"items,omitempty"`
	AdditionalProperties *bool                    `json:"additionalProperties,omitempty"`
	// contains filtered or unexported fields
}

PortFieldInfo describes metadata for PortDefinition fields

type PortKind

type PortKind string

PortKind is the closed vocabulary of semantic component port kinds.

const (
	PortKindTimer        PortKind = "timer"
	PortKindNetwork      PortKind = "network"
	PortKindFile         PortKind = "file"
	PortKindHTTPClient   PortKind = "http-client"
	PortKindNATS         PortKind = "nats"
	PortKindNATSRequest  PortKind = "nats-request"
	PortKindJetStream    PortKind = "jetstream"
	PortKindKVWatch      PortKind = "kv-watch"
	PortKindKVRead       PortKind = "kv-read"
	PortKindKVWrite      PortKind = "kv-write"
	PortKindStoreRead    PortKind = "store-read"
	PortKindStoreProvide PortKind = "store-provide"
)

Canonical port kinds. Alternate spellings and custom kinds are not accepted.

type Portable

type Portable interface {
	ResourceID() string
	IsExclusive() bool
	Kind() PortKind
}

Portable is the common semantic contract implemented by every port config.

type PropertySchema

type PropertySchema struct {
	Type        string `json:"type"` // "string", "int", "bool", "float", "enum", "array", "object", "ports", "cache"
	Description string `json:"description"`
	// Default is a JSON value: nil, a string, a bool, a number, a []string,
	// or a []any or map[string]any whose elements are these, at any depth.
	// The registry copies such a default when it stores or lists a schema. A
	// default of any other type is stored as is, so a pointer, slice or map
	// it holds stays shared with the caller.
	Default     any                       `json:"default,omitempty"`
	Enum        []string                  `json:"enum,omitempty"`        // Valid string values
	Minimum     *int                      `json:"minimum,omitempty"`     // For numeric types
	Maximum     *int                      `json:"maximum,omitempty"`     // For numeric types
	MinLength   *int                      `json:"minLength,omitempty"`   // Minimum string length
	MaxLength   *int                      `json:"maxLength,omitempty"`   // Maximum string length
	Pattern     string                    `json:"pattern,omitempty"`     // Regular expression for string values
	Category    string                    `json:"category,omitempty"`    // "basic" or "advanced" for UI organization
	PortFields  map[string]PortFieldInfo  `json:"portFields,omitempty"`  // Metadata for port fields (when type is "ports")
	CacheFields map[string]CacheFieldInfo `json:"cacheFields,omitempty"` // Metadata for cache fields (when type is "cache")
	Properties  map[string]PropertySchema `json:"properties,omitempty"`  // Nested properties for object types
	// AdditionalProperties controls whether object fields outside Properties
	// are accepted. nil preserves JSON Schema's permissive default.
	AdditionalProperties *bool           `json:"additionalProperties,omitempty"`
	Required             []string        `json:"required,omitempty"` // Required nested fields for object types
	Items                *PropertySchema `json:"items,omitempty"`    // Item schema for array types
}

PropertySchema describes a single configuration property

type Registration

type Registration struct {
	Name         string              `json:"name"`         // Factory name (e.g., "udp-input")
	Type         types.ComponentType `json:"type"`         // One of the five types.ComponentType constants
	Protocol     string              `json:"protocol"`     // Technical protocol (udp, mavlink, websocket, etc.)
	Domain       string              `json:"domain"`       // Business domain (robotics, semantic, network, storage)
	Description  string              `json:"description"`  // Human-readable description
	Version      string              `json:"version"`      // Component version
	Schema       ConfigSchema        `json:"schema"`       // Schema as static metadata (Feature 011)
	Factory      Factory             `json:"-"`            // Factory function (not serializable)
	Ports        PortDeclarer        `json:"-"`            // Static port declaration (not serializable)
	Dependencies []string            `json:"dependencies"` // Boot dependencies such as DepModelRegistry
}

Registration holds factory and metadata for a component type

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry manages component factories and immutable admitted declarations. Runtime component handles remain private to ComponentManager.

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates a new empty component registry

func (*Registry) CreateComponent

func (r *Registry) CreateComponent(
	instanceName string,
	config types.ComponentConfig,
	deps Dependencies,
	prepare func(Discoverable) error,
) (Discoverable, error)

CreateComponent is the boot-admission seam. It exists for the component manager (service.ComponentManager): a consumer creates and composes components through that manager, and a direct call bypasses the manager's bookkeeping. prepare must finish all fallible owner-local setup before the Registry publishes the immutable declaration.

func (*Registry) Declare

func (r *Registry) Declare(instanceName string, config types.ComponentConfig) (Declaration, error)

Declare evaluates the named factory's port declarer for one configured instance and resolves the result through the canonical port resolver. It constructs nothing and needs no dependencies: this is the offline half of the declaration the Registry verifies at admission.

func (*Registry) ListFactories

func (r *Registry) ListFactories() map[string]*Registration

ListFactories returns all registered component factories This provides information about what types of components can be created.

func (*Registry) Register

func (r *Registry) Register(registration Registration) error

Register registers a component factory under registration.Name. It refuses, with an error of the invalid class naming the factory, a name ValidateComponentName refuses, a nil Factory or Ports, a Type that is not one of the five types.ComponentType constants, and a name already registered. The registry keeps its own copy: a later change to the caller's value, its schema or its dependency list changes nothing registered. The one exception is a schema default that is not a JSON value (PropertySchema.Default): it is stored as is, so a pointer, slice or map it holds stays shared.

func (*Registry) SealComposition

func (r *Registry) SealComposition()

SealComposition closes boot admission for the current process. It exists for the component manager (service.ComponentManager), which seals the composition once boot admission is complete; a direct call bypasses the manager's bookkeeping.

func (*Registry) Snapshots

func (r *Registry) Snapshots() []Declaration

Snapshots returns the admitted declarations, sorted by instance name. Each is a copy that shares no slice with the registry. It exists for the component manager (service.ComponentManager): a consumer reads admitted components through that manager, and a direct call bypasses the manager's bookkeeping. The message logger (service.MessageLogger) is its second reader: with "*" it monitors the subjects the admitted declarations name.

type SchemaDirectives

type SchemaDirectives struct {
	// core (required)
	Type        string // REQUIRED - field type
	Description string // REQUIRED (warning if missing)

	// UI Organization
	Category string // "basic" or "advanced"
	ReadOnly bool   // For PortDefinition fields
	Editable bool   // For PortDefinition fields
	Hidden   bool   // Hide from UI

	// Constraints
	Default  any      // Type-specific default value (stored as string, converted during schema generation)
	Required bool     // Field must be provided
	Min      *int     // Numeric minimum
	Max      *int     // Numeric maximum
	Enum     []string // Valid enum values

	// Future extensions (stored but not used yet)
	Help        string
	Placeholder string
	Pattern     string
	Format      string
}

SchemaDirectives represents parsed schema tag directives

func ParseSchemaTag

func ParseSchemaTag(tag string) (SchemaDirectives, error)

ParseSchemaTag parses a schema struct tag into directives.

Tag Syntax:

  • Directives are comma-separated
  • Key-value pairs use colon: "key:value"
  • Boolean flags have no colon: "readonly", "required"
  • Enum values are pipe-separated: "enum:val1|val2|val3"
  • Whitespace is trimmed from all values

Required Directives:

  • type: Field data type (string, int, bool, float, enum, array, object, ports)

Recommended Directives:

  • description: Human-readable field description (used for UI and documentation)

Optional Directives:

  • category: UI organization (basic, advanced)
  • default: Default value (converted to appropriate type)
  • min/max: Numeric constraints
  • enum: Valid values for enum types (pipe-separated)
  • readonly: Field is read-only (boolean flag)
  • editable: Field is user-editable (boolean flag)
  • hidden: Field is hidden from UI (boolean flag)
  • required: Field must be provided (boolean flag)

Example Tags:

schema:"type:string,description:Component name,category:basic"
schema:"type:int,description:Port,min:1,max:65535,default:8080"
schema:"type:enum,description:Level,enum:debug|info|warn,default:info"
schema:"required,type:string,description:API key"
schema:"readonly,type:string,description:System ID"

Returns an error if:

  • Tag is empty
  • Type directive is missing
  • Type value is invalid
  • Directive syntax is malformed
  • Numeric values cannot be parsed

See SCHEMA_TAG_SPEC.md for complete specification.

Example

ExampleParseSchemaTag demonstrates parsing individual schema tags

package main

import (
	"fmt"

	"github.com/c360studio/semengine/component"
)

func main() {
	// Parse a simple field tag
	tag := "type:int,description:Port number,min:1,max:65535,default:8080"
	directives, err := component.ParseSchemaTag(tag)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	fmt.Printf("Type: %s\n", directives.Type)
	fmt.Printf("Description: %s\n", directives.Description)
	fmt.Printf("Min: %d\n", *directives.Min)
	fmt.Printf("Max: %d\n", *directives.Max)
	fmt.Printf("Default: %s\n", directives.Default)

}
Output:
Type: int
Description: Port number
Min: 1
Max: 65535
Default: 8080
Example (Enum)

ExampleParseSchemaTag_enum demonstrates parsing enum tags

package main

import (
	"fmt"

	"github.com/c360studio/semengine/component"
)

func main() {
	tag := "type:enum,description:Log level,enum:debug|info|warn|error,default:info"
	directives, _ := component.ParseSchemaTag(tag)

	fmt.Printf("Type: %s\n", directives.Type)
	fmt.Printf("Description: %s\n", directives.Description)
	fmt.Printf("Enum values: %v\n", directives.Enum)
	fmt.Printf("Default: %s\n", directives.Default)

}
Output:
Type: enum
Description: Log level
Enum values: [debug info warn error]
Default: info
Example (Flags)

ExampleParseSchemaTag_flags demonstrates boolean flags

package main

import (
	"fmt"

	"github.com/c360studio/semengine/component"
)

func main() {
	tag := "required,readonly,type:string,description:System identifier"
	directives, _ := component.ParseSchemaTag(tag)

	fmt.Printf("Type: %s\n", directives.Type)
	fmt.Printf("Required: %v\n", directives.Required)
	fmt.Printf("ReadOnly: %v\n", directives.ReadOnly)

}
Output:
Type: string
Required: true
ReadOnly: true

type State

type State int

State represents the current lifecycle state of a component

const (
	// StateCreated indicates component was created but not initialized
	StateCreated State = iota
	// StateInitialized indicates component was initialized but not started
	StateInitialized
	// StateStarted indicates component is running
	StateStarted
	// StateStopped indicates component was stopped
	StateStopped
	// StateFailed indicates component failed during lifecycle operation
	StateFailed
)

func (State) String

func (cs State) String() string

String returns a string representation of the component state

type StoreProvidePort

type StoreProvidePort struct {
	Instance string `json:"instance"` // StorageInstance name this component owns
}

StoreProvidePort declares that a storage component OWNS (provides) a store instance, addressable by its StorageInstance name (ADR-063). It is the flowgraph marker for store ownership and complements the StoreProvider interface the ComponentManager reads to populate the shared StoreRegistry.

Non-exclusive by design. Duplicate live Store ownership is owner-local runtime state and remains enforced by storeregistry.Register; it is not a declaration-derived exclusive-resource claim.

func (StoreProvidePort) IsExclusive

func (s StoreProvidePort) IsExclusive() bool

IsExclusive returns false — ownership conflicts are caught at registry-population time, not here (see the type doc).

func (StoreProvidePort) Kind

func (s StoreProvidePort) Kind() PortKind

Kind returns the canonical port kind.

func (StoreProvidePort) ResourceID

func (s StoreProvidePort) ResourceID() string

ResourceID returns a unique identifier for store provide ports.

type StoreProvider

type StoreProvider interface {
	ProvidedStores() map[string]storage.StreamableStore
}

StoreProvider is implemented by storage components that own one or more stores addressable by StorageInstance name (ADR-063). For the boot-composed component set, ComponentManager reads this AFTER a component Starts to populate the shared StoreRegistry and clears those entries when the component Stops. A desired-state write does not swap a handle in the running process.

The map is keyed by the StorageInstance name each store STAMPS into refs (store.InstanceName()), so the registry key, the store-provide port token, and the ref's StorageInstance are the same value by construction. Returns nil/empty before Start (no store yet) or for a component that provides no store.

type StoreReadPort

type StoreReadPort struct {
	Bucket    string             `json:"bucket"`              // Storage bucket name (e.g., "MESSAGES")
	Interface *InterfaceContract `json:"interface,omitempty"` // Optional content type contract
}

StoreReadPort declares streaming read access to a content storage bucket. Components use this to read large content (documents, images, video) from storage backends (NATS ObjectStore, filesystem, etc.) without coupling to a specific backend implementation.

func (StoreReadPort) IsExclusive

func (s StoreReadPort) IsExclusive() bool

IsExclusive returns false as multiple readers are allowed

func (StoreReadPort) Kind

func (s StoreReadPort) Kind() PortKind

Kind returns the canonical port kind.

func (StoreReadPort) ResourceID

func (s StoreReadPort) ResourceID() string

ResourceID returns unique identifier for store read ports

type StreamFacts

type StreamFacts struct {
	// contains filtered or unexported fields
}

StreamFacts is the immutable JetStream-specific portion of PortFacts.

func (StreamFacts) AckPolicy

func (f StreamFacts) AckPolicy() string

AckPolicy returns the declared consumer acknowledgement policy.

func (StreamFacts) AckWait

func (f StreamFacts) AckWait() string

AckWait returns the declared acknowledgement timeout.

func (StreamFacts) DeliverPolicy

func (f StreamFacts) DeliverPolicy() string

DeliverPolicy returns the declared consumer delivery policy.

func (StreamFacts) HeartbeatInterval

func (f StreamFacts) HeartbeatInterval() string

HeartbeatInterval returns the declared consumer heartbeat interval.

func (StreamFacts) Import

func (f StreamFacts) Import() bool

Import reports whether the operator declared this port an import lane — the one place a foreign org.platform is admitted (ADR-102 decision 5). False is the fail-closed default for every port that does not say otherwise.

func (StreamFacts) MaxAckPending

func (f StreamFacts) MaxAckPending() int

MaxAckPending returns the declared unacknowledged-message ceiling.

func (StreamFacts) MaxDeliver

func (f StreamFacts) MaxDeliver() int

MaxDeliver returns the declared maximum delivery attempts.

func (StreamFacts) MaxSizeGB

func (f StreamFacts) MaxSizeGB() int

MaxSizeGB returns the declared stream size limit in GiB.

func (StreamFacts) Name

func (f StreamFacts) Name() string

Name returns the declared stream name.

func (StreamFacts) Replicas

func (f StreamFacts) Replicas() int

Replicas returns the declared stream replica count.

func (StreamFacts) RetentionDays

func (f StreamFacts) RetentionDays() int

RetentionDays returns the declared stream retention duration in days.

func (StreamFacts) RetentionPolicy

func (f StreamFacts) RetentionPolicy() string

RetentionPolicy returns the declared JetStream retention policy.

func (StreamFacts) Storage

func (f StreamFacts) Storage() string

Storage returns the declared JetStream storage mode.

func (StreamFacts) Subjects

func (f StreamFacts) Subjects() []string

Subjects returns a defensive copy of the declared subjects.

type TimerPort

type TimerPort struct {
	Interval  string             `json:"interval"` // Duration string e.g. "30s", "1m"
	Interface *InterfaceContract `json:"interface,omitempty"`
}

TimerPort represents a periodic timer trigger port

func (TimerPort) IsExclusive

func (t TimerPort) IsExclusive() bool

IsExclusive returns false as multiple timers can run independently

func (TimerPort) Kind

func (t TimerPort) Kind() PortKind

Kind returns the canonical port kind.

func (TimerPort) ResourceID

func (t TimerPort) ResourceID() string

ResourceID returns unique identifier for timer ports

type Validatable

type Validatable interface {
	Validate() error
}

Validatable interface for configs that can self-validate

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL