# Go interfaces (/brain/docs/adapters/interfaces)

Extracted directly from Go source during the documentation build. Application code imports public aliases from `github.com/aexhq/brain` for harnesses, providers, handlers, and session contracts. The public `Server` owns stock persistence and transport implementations. Repository and checkpoint adapter seams remain internal. See the [Go application SDK](/brain/docs/sdks/application).

## harness [#harness]

### Factory [#factory]

```go
package harness // import "github.com/aexhq/brain/internal/harness"

type Factory interface {
	Open(context.Context, Options) (Runner, error)
	SupportsSteering() bool
}
```

### Runner [#runner]

```go
package harness // import "github.com/aexhq/brain/internal/harness"

type Runner interface {
	Prompt(context.Context, string) error
	Steer(context.Context, string) error
	Interrupt(context.Context) error
	Checkpoint(context.Context) ([]core.NativeFile, error)
	Close() error
}
```

### Options [#options]

```go
package harness // import "github.com/aexhq/brain/internal/harness"

type Options struct {
	Lifetime  context.Context                                       `json:"-"`
	SessionID string                                                `json:"session_id"`
	Dir       string                                                `json:"dir"`
	Config    core.Config                                           `json:"config"`
	Tools     []core.Tool                                           `json:"tools"`
	Provider  Provider                                              `json:"provider"`
	Event     func(string, json.RawMessage) error                   `json:"-"`
	Call      func(context.Context, core.Call) (core.Result, error) `json:"-"`
}
```

### RunnerFrame [#runnerframe]

```go
package harness // import "github.com/aexhq/brain/internal/harness"

type RunnerFrame struct {
	Attachment string          `json:"attachment"`
	Turn       string          `json:"turn,omitempty"`
	ID         string          `json:"id,omitempty"`
	Method     string          `json:"method,omitempty"`
	Params     json.RawMessage `json:"params,omitempty"`
	Result     json.RawMessage `json:"result,omitempty"`
	Error      *core.Error     `json:"error,omitempty"`
	Event      string          `json:"event,omitempty"`
	Data       json.RawMessage `json:"data,omitempty"`
}
```

## persistence [#persistence]

### Objects [#objects]

```go
package persistence // import "github.com/aexhq/brain/internal/persistence"

type Objects interface {
	Put(context.Context, string, []byte, bool) error
	Get(context.Context, string) ([]byte, error)
}

func NewObjects(ctx context.Context, s Settings) (Objects, error)
```

### Metadata [#metadata]

```go
package persistence // import "github.com/aexhq/brain/internal/persistence"

// Metadata is an eventual discovery index, never a session ownership lock.
type Metadata interface {
	Put(context.Context, core.Session, string) error
	Get(context.Context, string, string) (core.Session, string, error)
	List(context.Context, string, string, int) ([]core.Session, error)
	Close() error
}
```

## session [#session]

### Repository [#repository]

```go
package session // import "github.com/aexhq/brain/internal/session"

// Repository is the local state consumed by the session owner. Metadata writes
// are durable before returning. Root and Dir identify the local workspace used
// by native harnesses and staged recovery; remote databases do not replace it.
// The composition root owns Close, after Engine.Shutdown has drained executions.
type Repository interface {
	Create(context.Context, core.Session) error
	Get(context.Context, string) (core.Session, error)
	Save(context.Context, core.Session) error
	List(context.Context, string, string, int) ([]core.Session, error)
	Scan(context.Context, string, int) ([]core.Session, error)
	Import(context.Context, core.Session) error
	Root() string
	Dir(string) (string, error)
}
```

### ToolExecutor [#toolexecutor]

```go
package session // import "github.com/aexhq/brain/internal/session"

// ToolExecutor applies authorization and dispatch policy outside scheduling.
// Calls honor cancellation, do not retry, and return model-visible failures.
type ToolExecutor interface {
	Bind(context.Context, *core.Session) error
	Describe(context.Context, core.Session) ([]core.Tool, error)
	NeedsInspection(string) bool
	Invoke(context.Context, core.Session, core.ToolScope, core.Call, func(json.RawMessage)) (core.Result, error)
}
```

### Checkpoints [#checkpoints]

```go
package session // import "github.com/aexhq/brain/internal/session"

// Checkpoints publishes and restores immutable snapshots without inference.
// List is eventual discovery; it must never be used as an ownership lock.
type Checkpoints interface {
	Publish(context.Context, persistence.Snapshot) (persistence.Manifest, error)
	Restore(context.Context, string, string, string, string) (persistence.Manifest, string, error)
	List(context.Context, string, string, int) ([]core.Session, error)
}
```

## store [#store]

### Metadata [#metadata-1]

```go
package store // import "github.com/aexhq/brain/internal/store"

// Metadata is the authoritative local session database, not an eventual index.
// Writes are durable on return. Save and Import must never change a tenant.
// List and Scan return ascending IDs strictly after the supplied cursor.
// Missing Get/Save returns core.NotFound; conflicting Import returns core.Forbidden.
// Implementations must support concurrent calls and context cancellation.
type Metadata interface {
	Create(context.Context, core.Session) error
	Get(context.Context, string) (core.Session, error)
	Save(context.Context, core.Session) error
	List(context.Context, string, string, int) ([]core.Session, error)
	Scan(context.Context, string, int) ([]core.Session, error)
	Import(context.Context, core.Session) error
	Close() error
}
```

## tools [#tools]

### Transport [#transport]

```go
package tools // import "github.com/aexhq/brain/internal/tools"

// Transport executes a single authorized, validated call. It must honor ctx,
// bound protocol reads, preserve outcome ambiguity, and never retry an action.
// The registry owns transports after NewWithTransports succeeds.
type Transport interface {
	Call(context.Context, Binding, Request, func(json.RawMessage)) core.Result
	Close()
}
```

### Binding [#binding]

```go
package tools // import "github.com/aexhq/brain/internal/tools"

type Binding struct {
	Handler    Handler      `json:"-"`
	Credential string       `json:"-"`
	Stdio      *StdioConfig `json:"-"`
	core.Tool
	Transport      string   `json:"transport,omitempty"`
	URL            string   `json:"url"`
	MCPTool        string   `json:"mcp_tool,omitempty"`
	TokenEnv       string   `json:"token_env,omitempty"`
	Tenants        []string `json:"tenants"`
	TimeoutSeconds int      `json:"timeout_seconds,omitempty"`
	MaxOutputBytes int64    `json:"max_output_bytes,omitempty"`
	InspectSession bool     `json:"inspect_session,omitempty"`
}

func DiscoverMCP(ctx context.Context, binding Binding, names []string) ([]Binding, error)
```

### Request [#request]

```go
package tools // import "github.com/aexhq/brain/internal/tools"

type Request struct {
	core.ToolScope
	Arguments json.RawMessage `json:"arguments"`
}
```