assist

type AccessResult struct {
	Role  *api.RoleDraft  `json:"role,omitempty"`
	Group *api.GroupDraft `json:"group,omitempty"`
	Reply string          `json:"reply"`

	// Refused is what the adapter proposed and Pando would not draft, each
	// with its reason.
	Refused []string `json:"refused,omitempty"`
	Ran
}

type Assignments struct {
	Store    Store
	Registry *api.Registry
	Declared []Declared

	// Name returns an adapter's display name, for refusals: "the Anthropic
	// adapter (ai_anthropic)" is clearer than the ID alone. Nil uses the ID.
	Name func(ref string) string
}

type AuditResult struct {
	Filter    api.AuditFilter `json:"filter"`
	Note      string          `json:"note,omitempty"`
	Summary   string          `json:"summary"`
	Matched   int             `json:"matched"`
	Truncated bool            `json:"truncated"`
	Ran
}

type Declared struct {
	Function api.AIFunction
	Adapter  string
	Model    string
	Source   Source
}

type Function struct {
	Function api.AIFunction `json:"function"`
	Title    string         `json:"title"`

	// AdapterID is empty when nothing is assigned.
	AdapterID string `json:"adapter_id,omitempty"`

	// Model is the assignment's model, empty for the adapter's own.
	// EffectiveModel is what runs: this, else the adapter's default.
	Model          string `json:"model,omitempty"`
	EffectiveModel string `json:"effective_model,omitempty"`

	// On is whether a call would reach an adapter now. Off says why.
	On  bool   `json:"on"`
	Off string `json:"off,omitempty"`

	Source *Source `json:"source,omitempty"`

	// Overridden is a stored assignment the startup configuration replaces.
	// Remove the declaration and restart, and it applies again.
	Overridden *state.AIAssignment `json:"overridden,omitempty"`
}

type PolicyChange struct {
	Key  string          `json:"key"`
	From json.RawMessage `json:"from"`
	To   json.RawMessage `json:"to"`
}

type PolicyDeclined struct {
	Key    string        `json:"key"`
	Reason string        `json:"reason"`
	Source policy.Source `json:"source"`
}

type PolicyResult struct {
	Proposed policy.Document  `json:"proposed"`
	Changes  []PolicyChange   `json:"changes"`
	Declined []PolicyDeclined `json:"declined,omitempty"`
	Refused  []string         `json:"refused,omitempty"`
	Reply    string           `json:"reply"`
	Ran
}

type Ran struct {
	AdapterID string `json:"adapter_id"`
	Model     string `json:"model"`
}

type ReferenceResult struct {
	Answer  string   `json:"answer"`
	Cites   []string `json:"cites"`
	Covered bool     `json:"covered"`
	Ran
}

type Service struct {
	Registry *api.Registry

	// Users, Apps and Groups are searched, never listed whole (O-54): every
	// read here is bounded by a limit or a set of IDs.
	Users interface {
		Search(ctx context.Context, q string, limit int) ([]state.User, error)
		ListPage(ctx context.Context, page state.Page) ([]state.User, string, int, error)
	}
	Apps interface {
		ListAllPage(ctx context.Context, page state.Page) ([]state.App, string, int, error)
		ListForPrincipalPage(ctx context.Context, p authz.Principal, page state.Page) ([]state.App, string, int, error)
	}
	Groups interface {
		Search(ctx context.Context, q string, limit int) ([]state.Group, error)
	}

	// Roles are read whole: the built-in roles and the custom ones an
	// administrator made, which a draft must not duplicate (R-082). Their
	// number is set by people defining roles by hand, not by the size of the
	// organization.
	Roles interface {
		List(ctx context.Context) ([]state.RoleRow, error)
	}

	// Verbs is what a principal holds install-wide, which bounds what an
	// access draft may grant and what the AI may look up for them.
	Verbs interface {
		InstallVerbsFor(ctx context.Context, p authz.Principal) ([]string, error)
	}

	// Policy reads the effective policy document, startup fields included;
	// Overlay says which fields those are and where each was set.
	Policy interface {
		Load(ctx context.Context) (policy.Document, error)
	}
	Overlay *policy.Overlay

	// Audit runs the filter an audit search becomes. The action names the
	// adapter chooses from are audit.Actions, the code's own catalog (O-54).
	Audit interface {
		List(ctx context.Context, q audit.Query) ([]audit.Record, error)
	}

	// Reference is the generated reference in Markdown.
	Reference func() string

	// Now is the clock. Nil is the system clock.
	Now func() time.Time

	Timeout time.Duration
}

type Source struct {
	// Kind is "database" or "file".
	Kind string `json:"kind"`
	// Name is the config file's path.
	Name string `json:"name,omitempty"`
	// Key is the key inside the config file.
	Key string `json:"key,omitempty"`
}

type Store interface {
	List(ctx context.Context) ([]state.AIAssignment, error)
	Put(ctx context.Context, a state.AIAssignment) error
	Delete(ctx context.Context, function string) error
}