go/docs/RFC.md

Core API Contract (RFC)

This file is the canonical API catalog for dappco.re/go/core.

• Exports follow the core.Result contract ({Value any, OK bool}) for outcomes.
• Inputs are passed as core.Options collections of core.Option key-value pairs.
• All method and function examples below compile against current repository behavior.

1) Core construction and top-level bootstrap types

type CoreOption func(*Core) Result

func customOption(*core.Core) core.Result

func New(opts ...CoreOption) *Core

c := core.New(
    core.WithOption("name", "agent"),
    core.WithService(process.Register),
    core.WithServiceLock(),
)

func WithOptions(opts Options) CoreOption

c := core.New(core.WithOptions(core.NewOptions(
    core.Option{Key: "name", Value: "agent"},
)))

func WithService(factory func(*Core) Result) CoreOption

c := core.New(core.WithService(process.Register))

func WithName(name string, factory func(*Core) Result) CoreOption

c := core.New(core.WithName("process", process.Register))

func WithOption(key string, value any) CoreOption

c := core.New(
    core.WithOption("name", "agent"),
    core.WithOption("debug", true),
)

func WithServiceLock() CoreOption

c := core.New(
    core.WithService(auth.Register),
    core.WithServiceLock(),
)

type ServiceFactory func() Result

type ServiceFactory func() core.Result

func NewWithFactories(app any, factories map[string]ServiceFactory) Result

r := core.NewWithFactories(nil, map[string]core.ServiceFactory{
    "audit": func() core.Result {
        return core.Result{Value: mySvc(core.NewServiceRuntime(core.Core, core.MyOptions{})), OK: true}
    },
})
if !r.OK { panic(r.Value) }

func NewRuntime(app any) Result

r := core.NewRuntime(nil)
runtime := r.Value.(*core.Runtime)

type Runtime struct

• app any
• Core *Core

func (r *Runtime) ServiceName() string

name := rt.ServiceName() // "Core"

func (r *Runtime) ServiceStartup(ctx context.Context, options any) Result

r := rt.ServiceStartup(context.Background(), nil)

func (r *Runtime) ServiceShutdown(ctx context.Context) Result

r := rt.ServiceShutdown(context.Background())

2) Core accessors and lifecycle

type Core struct

func (c *Core) Options() *Options

name := c.Options().String("name")

func (c *Core) App() *App

appName := c.App().Name

func (c *Core) Data() *Data

r := c.Data().ReadString("brain/prompt.md")

func (c *Core) Drive() *Drive

r := c.Drive().Get("api")

func (c *Core) Fs() *Fs

r := c.Fs().Write("status.json", "ok")

func (c *Core) Config() *Config

c.Config().Set("debug", true)

func (c *Core) Error() *ErrorPanic

defer c.Error().Recover()

func (c *Core) Log() *ErrorLog

_ = c.Log().Info("boot")

func (c *Core) Cli() *Cli

c.Cli().SetBanner(func(_ *core.Cli) string { return "agent" })

func (c *Core) IPC() *Ipc

c.RegisterAction(func(_ *core.Core, _ core.Message) core.Result { return core.Result{OK: true} })

func (c *Core) I18n() *I18n

_ = c.I18n().Language()

func (c *Core) Env(key string) string

home := c.Env("DIR_HOME")

func (c *Core) Context() context.Context

goCtx := c.Context()

func (c *Core) Core() *Core

self := c.Core()

func (c *Core) RunE() error

if err := c.RunE(); err != nil { /* handle */ }

func (c *Core) Run()

c.Run()

func (c *Core) ACTION(msg Message) Result

c.ACTION(core.ActionServiceStartup{})

func (c *Core) QUERY(q Query) Result

r := c.QUERY(core.NewOptions(core.Option{Key: "name", Value: "agent"}))

func (c *Core) QUERYALL(q Query) Result

r := c.QUERYALL(core.NewOptions())

func (c *Core) LogError(err error, op, msg string) Result

_ = c.LogError(err, "core.Start", "startup failed")

func (c *Core) LogWarn(err error, op, msg string) Result

_ = c.LogWarn(err, "agent.Check", "warning")

func (c *Core) Must(err error, op, msg string)

c.Must(err, "core.op", "must hold")

func (c *Core) RegistryOf(name string) *Registry[any]

svcNames := c.RegistryOf("services").Names()

3) Service and lifecycle discovery APIs

type Service struct

type Service struct {
    Name string
    Instance any
    Options Options
    OnStart  func() Result
    OnStop   func() Result
    OnReload func() Result
}

func (c *Core) Service(name string, service ...Service) Result

_ = c.Service("cache", core.Service{
    OnStart: func() core.Result { return core.Result{OK: true} },
    OnStop:  func() core.Result { return core.Result{OK: true} },
})

func (c *Core) RegisterService(name string, instance any) Result

_ = c.RegisterService("process", processSvc)

func (c *Core) Services() []string

names := c.Services()

func (c *Core) Lock(name string) *Lock

l := c.Lock("agent")
l.Mutex.Lock()
defer l.Mutex.Unlock()

func (c *Core) LockEnable(name ...string)

c.LockEnable()

func (c *Core) LockApply(name ...string)

c.LockApply()

func (c *Core) Startables() Result

r := c.Startables()

func (c *Core) Stoppables() Result

r := c.Stoppables()

func (c *Core) ServiceStartup(ctx context.Context, options any) Result

r := c.ServiceStartup(context.Background(), nil)

func (c *Core) ServiceShutdown(ctx context.Context) Result

r := c.ServiceShutdown(context.Background())

type ServiceRuntime[T any]

sr := core.NewServiceRuntime(c, MyServiceOptions{})

func NewServiceRuntime[T any](c *Core, opts T) *ServiceRuntime[T]

sr := core.NewServiceRuntime(c, core.MyOpts{})

func (r *ServiceRuntime[T]) Core() *Core

c := sr.Core()

func (r *ServiceRuntime[T]) Options() T

opts := sr.Options()

func (r *ServiceRuntime[T]) Config() *Config

cfg := sr.Config()

type ServiceRegistry struct

*Registry[*Service] + lockEnabled bool.

func ServiceFor[T any](c *Core, name string) (T, bool)

svc, ok := core.ServiceFor[*myService](c, "myservice")

func MustServiceFor[T any](c *Core, name string) T

svc := core.MustServiceFor[*myService](c, "myservice")

type Startable interface { OnStartup(context.Context) Result }

type Stoppable interface { OnShutdown(context.Context) Result }

4) Actions, Tasks, and message-driven capability primitives

type ActionHandler func(context.Context, Options) Result

var h ActionHandler = func(ctx context.Context, opts core.Options) core.Result { return core.Result{OK: true} }

type Action struct

a := c.Action("process.run")

func (a *Action) Run(ctx context.Context, opts Options) Result

r := a.Run(ctx, core.NewOptions(core.Option{Key: "command", Value: "go test"}))

func (a *Action) Exists() bool

if c.Action("process.run").Exists() { /* invoke */ }

func (c *Core) Action(name string, handler ...ActionHandler) *Action

c.Action("agent.echo", func(_ context.Context, opts core.Options) core.Result {
    return core.Result{Value: opts.String("msg"), OK: true}
})

func (c *Core) Actions() []string

names := c.Actions()

type Step struct

Action, With, Async, Input.

type Task struct

Name, Description, Steps.

func (t *Task) Run(ctx context.Context, c *Core, opts Options) Result

r := c.Task("deploy").Run(ctx, c, core.NewOptions())

func (c *Core) Task(name string, def ...Task) *Task

c.Task("deploy", core.Task{Steps: []core.Step{{Action: "agent.echo", Async: false}}})

func (c *Core) Tasks() []string

for _, n := range c.Tasks() {}

type Message any

c.ACTION(core.ActionTaskStarted{TaskIdentifier: "t1", Action: "agent.echo"})

type Query any

type statusQuery struct{}
_ = statusQuery{}

type QueryHandler func(*Core, Query) Result

func (c *Core) Query(q Query) Result

r := c.Query(core.Query("ping"))

func (c *Core) QueryAll(q Query) Result

r := c.QueryAll(core.Query("ping"))

func (c *Core) RegisterQuery(handler QueryHandler)

c.RegisterQuery(func(_ *core.Core, _ core.Query) core.Result { return core.Result{Value: "pong", OK: true} })

func (c *Core) RegisterAction(handler func(*Core, Message) Result)

c.RegisterAction(func(_ *core.Core, msg core.Message) core.Result { return core.Result{OK: true} })

func (c *Core) RegisterActions(handlers ...func(*Core, Message) Result)

c.RegisterActions(h1, h2)

func (c *Core) RemoteAction(name string, ctx context.Context, opts Options) Result

r := c.RemoteAction("charon:agent.status", ctx, core.NewOptions())

type ActionServiceStartup struct{}

type ActionServiceShutdown struct{}

type ActionTaskStarted struct

TaskIdentifier, Action, Options.

type ActionTaskProgress struct

TaskIdentifier, Action, Progress, Message.

type ActionTaskCompleted struct

TaskIdentifier, Action, Result.

5) Remote API and stream transport

type Stream interface

type Stream interface {
    Send(data []byte) error
    Receive() ([]byte, error)
    Close() error
}

type StreamFactory func(handle *DriveHandle) (Stream, error)

var f core.StreamFactory = func(h *core.DriveHandle) (core.Stream, error) { return nil, nil }

type API struct

func (c *Core) API() *API

_ = c.API()

func (a *API) RegisterProtocol(scheme string, factory StreamFactory)

c.API().RegisterProtocol("mcp", mcpStreamFactory)

func (a *API) Stream(name string) Result

r := c.API().Stream("api")

func (a *API) Call(endpoint, action string, opts Options) Result

r := c.API().Call("api", "agent.status", core.NewOptions())

func (a *API) Protocols() []string

names := c.API().Protocols()

6) Command and CLI layer

type CliOptions struct{}

type Cli struct

func CliRegister(c *Core) Result

_ = core.CliRegister(c)

func (cl *Cli) Print(format string, args ...any)

cl.Print("starting %s", "agent")

func (cl *Cli) SetOutput(w io.Writer)

cl.SetOutput(os.Stderr)

func (cl *Cli) Run(args ...string) Result

r := cl.Run("deploy", "to", "homelab")

func (cl *Cli) PrintHelp()

cl.PrintHelp()

func (cl *Core) SetBanner(fn func(*Cli) string)

cl.SetBanner(func(_ *core.Cli) string { return "agent-cli" })

func (cl *Cli) Banner() string

label := cl.Banner()

type CommandAction func(Options) Result

type Command struct

c.Command("deploy", core.Command{Action: func(opts core.Options) core.Result {
    return core.Result{Value: "ok", OK: true}
}})

func (cmd *Command) I18nKey() string

key := c.Command("deploy/to/homelab").Value.(*core.Command).I18nKey()

func (cmd *Command) Run(opts Options) Result

r := cmd.Run(core.NewOptions(core.Option{Key: "name", Value: "x"}))

func (cmd *Command) IsManaged() bool

if cmd.IsManaged() { /* managed lifecycle */ }

type CommandRegistry struct

*Registry[*Command].

func (c *Core) Command(path string, command ...Command) Result

c.Command("agent/deploy", core.Command{
    Action: func(opts core.Options) core.Result { return core.Result{OK: true} },
})

func (c *Core) Commands() []string

paths := c.Commands()

type Command fields

Name, Description, Path, Action, Managed, Flags, Hidden, internal commands.

7) Subsystems: App, Data, Drive, Fs, I18n, Process

type App struct

func (a App) New(opts Options) App

app := (core.App{}).New(core.NewOptions(
    core.Option{Key: "name", Value: "agent"},
))

func (a App) Find(filename, name string) Result

r := core.App{}.Find("go", "Go")

type Data struct

func (d *Data) New(opts Options) Result

r := c.Data().New(core.NewOptions(
    core.Option{Key: "name", Value: "brain"},
    core.Option{Key: "source", Value: brainFS},
    core.Option{Key: "path", Value: "prompts"},
))

func (d *Data) ReadFile(path string) Result

r := c.Data().ReadFile("brain/readme.md")

func (d *Data) ReadString(path string) Result

r := c.Data().ReadString("brain/readme.md")

func (d *Data) List(path string) Result

r := c.Data().List("brain/templates")

func (d *Data) ListNames(path string) Result

r := c.Data().ListNames("brain/templates")

func (d *Data) Extract(path, targetDir string, templateData any) Result

r := c.Data().Extract("brain/template", "/tmp/ws", map[string]string{"Name": "demo"})

func (d *Data) Mounts() []string

for _, m := range c.Data().Mounts() {}

type DriveHandle struct

Name, Transport, Options.

type Drive struct

func (d *Drive) New(opts Options) Result

r := c.Drive().New(core.NewOptions(
    core.Option{Key: "name", Value: "mcp"},
    core.Option{Key: "transport", Value: "mcp://localhost:1234"},
))

type Fs struct

func (m *Fs) New(root string) *Fs

fs := (&core.Fs{}).New("/tmp")

func (m *Fs) NewUnrestricted() *Fs

fs := (&core.Fs{}).NewUnrestricted()

func (m *Fs) Root() string

root := c.Fs().Root()

func (m *Fs) Read(p string) Result

r := c.Fs().Read("status.txt")

func (m *Fs) Write(p, content string) Result

_ = c.Fs().Write("status.txt", "ok")

func (m *Fs) WriteMode(p, content string, mode os.FileMode) Result

_ = c.Fs().WriteMode("secret", "x", 0600)

func (m *Fs) TempDir(prefix string) string

tmp := c.Fs().TempDir("agent-")

func (m *Fs) WriteAtomic(p, content string) Result

_ = c.Fs().WriteAtomic("status.json", "{\"ok\":true}")

func (m *Fs) EnsureDir(p string) Result

_ = c.Fs().EnsureDir("cache")

func (m *Fs) IsDir(p string) bool

ok := c.Fs().IsDir("cache")

func (m *Fs) IsFile(p string) bool

ok := c.Fs().IsFile("go.mod")

func (m *Fs) Exists(p string) bool

if c.Fs().Exists("go.mod") {}

func (m *Fs) List(p string) Result

r := c.Fs().List(".")

func (m *Fs) Stat(p string) Result

r := c.Fs().Stat("go.mod")

func (m *Fs) Open(p string) Result

r := c.Fs().Open("go.mod")

func (m *Fs) Create(p string) Result

r := c.Fs().Create("notes.txt")

func (m *Fs) Append(p string) Result

r := c.Fs().Append("notes.txt")

func (m *Fs) Rename(oldPath, newPath string) Result

_ = c.Fs().Rename("a.txt", "b.txt")

func (m *Fs) Delete(p string) Result

_ = c.Fs().Delete("tmp.txt")

func (m *Fs) DeleteAll(p string) Result

_ = c.Fs().DeleteAll("tmpdir")

func (m *Fs) ReadStream(path string) Result

r := c.Fs().ReadStream("go.mod")

func (m *Fs) WriteStream(path string) Result

r := c.Fs().WriteStream("go.mod")

Package functions in fs.go

func DirFS(dir string) fs.FS

fsys := core.DirFS("/tmp")

func ReadAll(reader any) Result

r := core.ReadAll(c.Fs().ReadStream("go.mod").Value)

func WriteAll(writer any, content string) Result

r := core.WriteAll(c.Fs().WriteStream("out.txt").Value, "value")

func CloseStream(v any)

core.CloseStream(handle)

type I18n struct

func (i *I18n) AddLocales(mounts ...*Embed)

c.I18n().AddLocales(emb)

func (i *I18n) Locales() Result

r := c.I18n().Locales()

func (i *I18n) SetTranslator(t Translator)

c.I18n().SetTranslator(translator)

func (i *I18n) Translator() Result

r := c.I18n().Translator()

func (i *I18n) Translate(messageID string, args ...any) Result

r := c.I18n().Translate("cmd.deploy.description")

func (i *I18n) SetLanguage(lang string) Result

r := c.I18n().SetLanguage("de")

func (i *I18n) Language() string

lang := c.I18n().Language()

func (i *I18n) AvailableLanguages() []string

langs := c.I18n().AvailableLanguages()

type Process struct

func (c *Core) Process() *Process

p := c.Process()

func (p *Process) Run(ctx context.Context, command string, args ...string) Result

r := c.Process().Run(ctx, "git", "status")

func (p *Process) RunIn(ctx context.Context, dir, command string, args ...string) Result

r := c.Process().RunIn(ctx, "/tmp", "go", "test", "./...")

func (p *Process) RunWithEnv(ctx context.Context, dir string, env []string, command string, args ...string) Result

r := c.Process().RunWithEnv(ctx, "/", []string{"CI=true"}, "go", "version")

func (p *Process) Start(ctx context.Context, opts Options) Result

r := c.Process().Start(ctx, core.NewOptions(core.Option{Key: "command", Value: "sleep"}))

func (p *Process) Kill(ctx context.Context, opts Options) Result

r := c.Process().Kill(ctx, core.NewOptions(core.Option{Key: "id", Value: "1234"))

func (p *Process) Exists() bool

if c.Process().Exists() {}

8) Task/background execution and progress

func (c *Core) PerformAsync(action string, opts Options) Result

r := c.PerformAsync("agent.dispatch", core.NewOptions(core.Option{Key: "id", Value: 1}))

func (c *Core) Progress(taskID string, progress float64, message string, action string)

c.Progress(taskID, 0.5, "halfway", "agent.dispatch")

func (c *Core) RegisterAction(handler func(*Core, Message) Result)

c.RegisterAction(func(_ *core.Core, msg core.Message) core.Result {
    _ = msg
    return core.Result{OK: true}
})

9) Logging and output

type Level int

const (
    core.LevelQuiet Level = iota
    core.LevelError
    core.LevelWarn
    core.LevelInfo
    core.LevelDebug
)

func (l Level) String() string

s := core.LevelInfo.String()

type Log struct

func NewLog(opts LogOptions) *Log

logger := core.NewLog(core.LogOptions{Level: core.LevelDebug})

func (l *Log) SetLevel(level Level)

logger.SetLevel(core.LevelWarn)

func (l *Log) Level() Level

lvl := logger.Level()

func (l *Log) SetOutput(w io.Writer)

logger.SetOutput(os.Stderr)

func (l *Log) SetRedactKeys(keys ...string)

logger.SetRedactKeys("token", "password")

func (l *Log) Debug(msg string, keyvals ...any)

logger.Debug("booted", "pid", 123)

func (l *Log) Info(msg string, keyvals ...any)

logger.Info("agent started")

func (l *Log) Warn(msg string, keyvals ...any)

logger.Warn("disk nearly full")

func (l *Log) Error(msg string, keyvals ...any)

logger.Error("failed to bind", "err", err)

func (l *Log) Security(msg string, keyvals ...any)

logger.Security("sandbox escape", "attempt", path)

type ErrorLog struct

func (el *ErrorLog) Error(err error, op, msg string) Result

r := c.Log().Error(err, "core.Run", "startup failed")

func (el *ErrorLog) Warn(err error, op, msg string) Result

r := c.Log().Warn(err, "warn", "soft error")

func (el *ErrorLog) Must(err error, op, msg string)

c.Log().Must(err, "core.maybe", "must hold")

type ErrorPanic struct

func (h *ErrorPanic) Recover()

defer c.Error().Recover()

func (h *ErrorPanic) SafeGo(fn func())

c.Error().SafeGo(func() { panic("boom") })

func (h *ErrorPanic) Reports(n int) Result

r := c.Error().Reports(3)

type LogErr struct

func NewLogErr(log *Log) *LogErr

le := core.NewLogErr(core.Default())

func (le *LogErr) Log(err error)

le.Log(err)

type LogPanic struct

func NewLogPanic(log *Log) *LogPanic

lp := core.NewLogPanic(core.Default())

func (lp *LogPanic) Recover()

defer lp.Recover()

Package-level logger helpers

Default, SetDefault, SetLevel, SetRedactKeys, Debug, Info, Warn, Error, Security.

func Default() *Log

l := core.Default()

func SetDefault(l *Log)

core.SetDefault(core.NewLog(core.LogOptions{Level: core.LevelDebug}))

func SetLevel(level Level)

core.SetLevel(core.LevelInfo)

func SetRedactKeys(keys ...string)

core.SetRedactKeys("password")

func Debug(msg string, keyvals ...any)

core.Debug("start")

func Info(msg string, keyvals ...any)

core.Info("ready")

func Warn(msg string, keyvals ...any)

core.Warn("high load")

func Error(msg string, keyvals ...any)

core.Error("failure", "err", err)

func Security(msg string, keyvals ...any)

core.Security("policy", "event", "denied")

type LogOptions struct

Level, Output, Rotation, RedactKeys.

type RotationLogOptions struct

Filename, MaxSize, MaxAge, MaxBackups, Compress.

var RotationWriterFactory func(RotationLogOptions) io.WriteCloser

core.RotationWriterFactory = myFactory

func Username() string

u := core.Username()

10) Error model and diagnostics

type Err struct

Operation, Message, Cause, Code.

func (e *Err) Error() string

_ = err.Error()

func (e *Err) Unwrap() error

_ = errors.Unwrap(err)

func E(op, msg string, err error) error

r := core.E("core.Run", "startup failed", err)

func Wrap(err error, op, msg string) error

r := core.Wrap(err, "api.Call", "request failed")

func WrapCode(err error, code, op, msg string) error

r := core.WrapCode(err, "NOT_AUTHORIZED", "api.Call", "forbidden")

func NewCode(code, msg string) error

_ = core.NewCode("VALIDATION", "invalid input")

func NewError(text string) error

_ = core.NewError("boom")

func ErrorJoin(errs ...error) error

err := core.ErrorJoin(e1, e2, e3)

func ErrorMessage(err error) string

msg := core.ErrorMessage(err)

func ErrorCode(err error) string

code := core.ErrorCode(err)

func Operation(err error) string

op := core.Operation(err)

func Root(err error) error

root := core.Root(err)

func AllOperations(err error) iter.Seq[string]

for op := range core.AllOperations(err) { fmt.Println(op) }

func StackTrace(err error) []string

stack := core.StackTrace(err)

func FormatStackTrace(err error) string

fmt.Println(core.FormatStackTrace(err))

func As(err error, target any) bool

var ee *core.Err
_ = core.As(err, &ee)

func Is(err, target error) bool

_ = core.Is(err, io.EOF)

type CrashReport struct

type CrashSystem struct

11) Asset packing and embed helpers

type AssetGroup struct

type AssetRef struct

type ScannedPackage struct

func AddAsset(group, name, data string)

core.AddAsset("g", "n", "payload")

func GetAsset(group, name string) Result

r := core.GetAsset("g", "n")

func GetAssetBytes(group, name string) Result

r := core.GetAssetBytes("g", "n")

func ScanAssets(filenames []string) Result

r := core.ScanAssets([]string{"main.go"})

func GeneratePack(pkg ScannedPackage) Result

r := core.GeneratePack(scanned)

func Mount(fsys fs.FS, basedir string) Result

r := core.Mount(appFS, "assets")

func MountEmbed(efs embed.FS, basedir string) Result

r := core.MountEmbed(efs, "assets")

func Extract(fsys fs.FS, targetDir string, data any, opts ...ExtractOptions) Result

r := core.Extract(embeds, "/tmp/out", map[string]string{"Name": "demo"})

type ExtractOptions struct

TemplateFilters []string, IgnoreFiles map[string]struct{}, RenameFiles map[string]string.

type Embed struct

func (s *Embed) Open(name string) Result

r := emb.Open("readme.md")

func (s *Embed) ReadDir(name string) Result

r := emb.ReadDir("templates")

func (s *Embed) ReadFile(name string) Result

r := emb.ReadFile("readme.md")

func (s *Embed) ReadString(name string) Result

r := emb.ReadString("readme.md")

func (s *Embed) Sub(subDir string) Result

r := emb.Sub("assets")

func (s *Embed) FS() fs.FS

fsys := emb.FS()

func (s *Embed) EmbedFS() embed.FS

efs := emb.EmbedFS()

func (s *Embed) BaseDirectory() string

base := emb.BaseDirectory()

12) Configuration and primitives

type Option struct

opt := core.Option{Key: "name", Value: "agent"}

type ConfigVar[T any]

func NewConfigVar[T any](val T) ConfigVar[T]

v := core.NewConfigVar("blue")

func (v *ConfigVar[T]) Get() T

val := v.Get()

func (v *ConfigVar[T]) Set(val T)

v.Set("red")

func (v *ConfigVar[T]) IsSet() bool

if v.IsSet() {}

func (v *ConfigVar[T]) Unset()

v.Unset()

type ConfigOptions struct

Settings map[string]any, Features map[string]bool.

type Config struct

func (e *Config) New() *Config

cfg := (&core.Config{}).New()

func (e *Config) Set(key string, val any)

cfg.Set("port", 8080)

func (e *Config) Get(key string) Result

r := cfg.Get("port")

func (e *Config) String(key string) string

v := cfg.String("port")

func (e *Config) Int(key string) int

v := cfg.Int("retries")

func (e *Config) Bool(key string) bool

v := cfg.Bool("debug")

func (e *Config) Enable(feature string)

e.Enable("tracing")

func (e *Config) Disable(feature string)

e.Disable("tracing")

func (e *Config) Enabled(feature string) bool

if e.Enabled("tracing") {}

func (e *Config) EnabledFeatures() []string

features := e.EnabledFeatures()

func ConfigGet[T any](e *Config, key string) T

limit := core.ConfigGet[int](cfg, "retries")

type Options struct

func NewOptions(items ...Option) Options

opts := core.NewOptions(core.Option{Key: "name", Value: "x"})

func (o *Options) Set(key string, value any)

opts.Set("debug", true)

func (o Options) Get(key string) Result

r := opts.Get("debug")

func (o Options) Has(key string) bool

if opts.Has("debug") {}

func (o Options) String(key string) string

v := opts.String("name")

func (o Options) Int(key string) int

v := opts.Int("port")

func (o Options) Bool(key string) bool

b := opts.Bool("debug")

func (o Options) Len() int

n := opts.Len()

func (o Options) Items() []Option

all := opts.Items()

type Result struct

func (r Result) Result(args ...any) Result

r := core.Result{}.Result(file, err)

func (r Result) New(args ...any) Result

r := core.Result{}.New(file, nil)

func (r Result) Get() Result

v := r.Get()

func JSONMarshal(v any) Result

r := core.JSONMarshal(map[string]string{"k": "v"})

func JSONMarshalString(v any) string

s := core.JSONMarshalString(map[string]any{"k": "v"})

func JSONUnmarshal(data []byte, target any) Result

r := core.JSONUnmarshal([]byte(`{"x":1}`), &cfg)

func JSONUnmarshalString(s string, target any) Result

r := core.JSONUnmarshalString(`{"x":1}`, &cfg)

13) Registry primitive

type Registry[T any] struct

func NewRegistry[T any]() *Registry[T]

r := core.NewRegistry[*core.Service]()

func (r *Registry[T]) Set(name string, item T) Result

r.Set("process", svc)

func (r *Registry[T]) Get(name string) Result

got := r.Get("process")

func (r *Registry[T]) Has(name string) bool

if r.Has("process") {}

func (r *Registry[T]) Names() []string

for _, n := range r.Names() {}

func (r *Registry[T]) List(pattern string) []T

vals := r.List("process.*")

func (r *Registry[T]) Each(fn func(string, T))

r.Each(func(name string, v *core.Service) {})

func (r *Registry[T]) Len() int

n := r.Len()

func (r *Registry[T]) Delete(name string) Result

_ = r.Delete("legacy")

func (r *Registry[T]) Disable(name string) Result

_ = r.Disable("legacy")

func (r *Registry[T]) Enable(name string) Result

_ = r.Enable("legacy")

func (r *Registry[T]) Disabled(name string) bool

if r.Disabled("legacy") {}

func (r *Registry[T]) Lock()

r.Lock()

func (r *Registry[T]) Locked() bool

locked := r.Locked()

func (r *Registry[T]) Seal()

r.Seal()

func (r *Registry[T]) Sealed() bool

if r.Sealed() {}

func (r *Registry[T]) Open()

r.Open()

14) Entitlement and security policy hooks

type Entitlement struct

Allowed, Unlimited, Limit, Used, Remaining, Reason.

func (e Entitlement) NearLimit(threshold float64) bool

if e.NearLimit(0.8) {}

func (e Entitlement) UsagePercent() float64

pct := e.UsagePercent()

type EntitlementChecker func(action string, quantity int, ctx context.Context) Entitlement

type UsageRecorder func(action string, quantity int, ctx context.Context)

func (c *Core) Entitled(action string, quantity ...int) Entitlement

e := c.Entitled("process.run")

func (c *Core) SetEntitlementChecker(checker EntitlementChecker)

c.SetEntitlementChecker(myChecker)

func (c *Core) RecordUsage(action string, quantity ...int)

c.RecordUsage("process.run")

func (c *Core) SetUsageRecorder(recorder UsageRecorder)

c.SetUsageRecorder(myRecorder)

15) Generic and helper collections

type Array[T comparable]

func NewArray[T comparable](items ...T) *Array[T]

arr := core.NewArray("a", "b")

func (s *Array[T]) Add(values ...T)

arr.Add("c")

func (s *Array[T]) AddUnique(values ...T)

arr.AddUnique("a")

func (s *Array[T]) Contains(val T) bool

_ = arr.Contains("a")

func (s *Array[T]) Filter(fn func(T) bool) Result

r := arr.Filter(func(v string) bool { return v != "x" })

func (s *Array[T]) Each(fn func(T))

arr.Each(func(v string) {})

func (s *Array[T]) Remove(val T)

arr.Remove("b")

func (s *Array[T]) Deduplicate()

arr.Deduplicate()

func (s *Array[T]) Len() int

n := arr.Len()

func (s *Array[T]) Clear()

arr.Clear()

func (s *Array[T]) AsSlice() []T

vals := arr.AsSlice()

16) String and path utility API

String helpers

• HasPrefix, HasSuffix, TrimPrefix, TrimSuffix, Contains, Split, SplitN, Join, Replace, Lower, Upper, Trim, RuneCount, NewBuilder, NewReader, Sprint, Sprintf, Concat.

core.Join("/", "deploy", "to", "homelab")
core.Concat("cmd.", "deploy", ".description")

Path helpers

• Path, PathBase, PathDir, PathExt, PathIsAbs, JoinPath, CleanPath, PathGlob.

core.Path("Code", "agent")
core.PathIsAbs("/tmp")

func JoinPath(segments ...string) string

p := core.JoinPath("workspace", "deploy", "main.go")

Generic I/O helpers

• Arg, ArgString, ArgInt, ArgBool, ParseFlag, FilterArgs, IsFlag, ID, ValidateName, SanitisePath.

id := core.ID()
name := core.ValidateName("agent").Value

Package-level functions in this section

func Print(w io.Writer, format string, args ...any)

core.Print(os.Stderr, "hello %s", "world")

func Println(args ...any)

core.Println("ready")

func Arg(index int, args ...any) Result

r := core.Arg(0, "x", 1)

func ArgString(index int, args ...any) string

v := core.ArgString(0, "x", 1)

func ArgInt(index int, args ...any) int

v := core.ArgInt(1, "x", 42)

func ArgBool(index int, args ...any) bool

v := core.ArgBool(2, true)

func IsFlag(arg string) bool

ok := core.IsFlag("--debug")

func ParseFlag(arg string) (string, string, bool)

key, val, ok := core.ParseFlag("--name=agent")

func FilterArgs(args []string) []string

clean := core.FilterArgs(os.Args[1:])

func ID() string

id := core.ID()

func ValidateName(name string) Result

r := core.ValidateName("deploy")

func SanitisePath(path string) string

safe := core.SanitisePath("../../etc")

func DirFS(dir string) fs.FS

root := core.DirFS("/tmp")

17) System and environment helpers

func Env(key string) string

home := core.Env("DIR_HOME")

func EnvKeys() []string

keys := core.EnvKeys()

func Username() string

who := core.Username()

18) Remaining interfaces and types

type ErrorSink interface

Error(msg string, keyvals ...any) and Warn(msg string, keyvals ...any).

type Stream interface

Send, Receive, Close as above.

type Translator interface

Translate, SetLanguage, Language, AvailableLanguages.

type LocaleProvider interface

Locales() *Embed.

type Runtime helpers

• type Ipc (named fields, no exported methods)
• type Lock struct{ Name string; Mutex *sync.RWMutex }
• type SysInfo struct{ values map[string]string }

type Ipc struct

ipc := c.IPC()

type Lock struct

guard := c.Lock("core-bootstrap")
guard.Mutex.Lock()
defer guard.Mutex.Unlock()

type SysInfo struct

// SysInfo values are accessed through Env()/EnvKeys(); direct type construction is not required.
home := core.Env("DIR_HOME")
keys := core.EnvKeys()

19) Legacy behavior notes

• Service lifecycle callbacks are the DTO fields OnStart and OnStop.
• Startable/Stoppable are the interface contracts and map to OnStartup(context.Context) / OnShutdown(context.Context).
• Registry iteration (Names, List, Each, Services, Startables, Stoppables) is insertion-order based via Registry.order.