souls

package
v1.5.0 Latest Latest
Warning

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

Go to latest
Published: Jun 12, 2026 License: AGPL-3.0 Imports: 20 Imported by: 0

Documentation

Overview

Package souls discovers principal-owned lesser souls and manages local incorporation bindings.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrHostTrustNotConfigured indicates the effective instance trust base URL is unavailable.
	ErrHostTrustNotConfigured = errors.New("host trust not configured")
	// ErrHostInstanceKeyMissing indicates no server-side Host instance key can be resolved.
	ErrHostInstanceKeyMissing = errors.New("host instance key missing")
	// ErrHostInstanceKeyUnavailable indicates the configured Host instance key secret could not be resolved.
	ErrHostInstanceKeyUnavailable = errors.New("host instance key unavailable")
	// ErrHostUnavailable indicates the Host instance-key API is unreachable or returned an unusable response.
	ErrHostUnavailable = errors.New("host unavailable")
	// ErrHostSigningPayloadUnsupported indicates Host returned signing metadata Lesser does not support.
	ErrHostSigningPayloadUnsupported = errors.New("host signing payload unsupported")
)
View Source
var (
	// ErrTrustNotConfigured indicates the instance trust base URL is unavailable.
	ErrTrustNotConfigured = errors.New("trust not configured")
	// ErrSoulNotAvailable indicates a soul is not available to the current authenticated principal.
	ErrSoulNotAvailable = errors.New("soul not available")
	// ErrSoulAlreadyBound indicates the target soul is already incorporated elsewhere.
	ErrSoulAlreadyBound = errors.New("soul already bound")
	// ErrTargetAgentRequired indicates the incorporation target agent identifier was omitted.
	ErrTargetAgentRequired = errors.New("target agent is required")
	// ErrTargetAgentNotFound indicates the requested local target agent does not exist.
	ErrTargetAgentNotFound = errors.New("target agent not found")
	// ErrTargetAgentMustBeAgent indicates the requested local target exists but is not an agent account.
	ErrTargetAgentMustBeAgent = errors.New("target account must be an agent")
	// ErrTargetAgentNotOwned indicates the requested local target agent is not owned by the authenticated principal.
	ErrTargetAgentNotOwned = errors.New("target agent not owned by authenticated principal")
	// ErrTargetAgentAlreadyHasSoul indicates the target local agent is already bound to another soul.
	ErrTargetAgentAlreadyHasSoul = errors.New("target agent already has soul")
)

Functions

This section is empty.

Types

type BootstrapBeginInput added in v1.5.0

type BootstrapBeginInput struct {
	// Username is the Lesser-local body handle Host receives as local_id.
	Username      string
	BodyID        string // Lesser-local state/UI identity; never serialized as Host local_id.
	WalletAddress string
	Capabilities  []string
}

BootstrapBeginInput is the Lesser-local request for Host registration begin.

type BootstrapBeginResult added in v1.5.0

type BootstrapBeginResult struct {
	RegistrationID  string
	HostSoulAgentID string
	WalletAddress   string
	WalletChallenge BootstrapWalletChallenge
	HostRequestID   string
}

BootstrapBeginResult contains Host begin output needed by the GraphQL state.

type BootstrapConversationCompleteInput added in v1.5.0

type BootstrapConversationCompleteInput struct {
	RegistrationID string
	ConversationID string
}

BootstrapConversationCompleteInput is the Lesser-local request for completing a Host mint conversation.

type BootstrapConversationCompleteResult added in v1.5.0

type BootstrapConversationCompleteResult struct {
	RegistrationID       string
	HostSoulAgentID      string
	ConversationID       string
	Status               string
	ProducedDeclarations string
	CompletedAt          *time.Time
	HostRequestID        string
}

BootstrapConversationCompleteResult contains Host completion state.

type BootstrapConversationMessageInput added in v1.5.0

type BootstrapConversationMessageInput struct {
	RegistrationID string
	ConversationID string
	Message        string
	Model          string
}

BootstrapConversationMessageInput is the Lesser-local request for sending a Host mint-conversation turn through the server-side instance-key route.

type BootstrapConversationMessageResult added in v1.5.0

type BootstrapConversationMessageResult struct {
	RegistrationID string
	ConversationID string
	Model          string
	FullResponse   string
	HostRequestID  string
}

BootstrapConversationMessageResult contains the Host conversation ids and terminal assistant response metadata collected from the SSE stream.

type BootstrapFinalizeInput added in v1.5.0

type BootstrapFinalizeInput struct {
	RegistrationID     string
	ConversationID     string
	BoundarySignatures map[string]string
	IssuedAt           time.Time
	ExpectedVersion    int
	SelfAttestation    string
}

BootstrapFinalizeInput is the Lesser-local request for Host hosted/off-chain finalize and publication.

type BootstrapFinalizePreflightInput added in v1.5.0

type BootstrapFinalizePreflightInput struct {
	RegistrationID     string
	ConversationID     string
	BoundarySignatures map[string]string
}

BootstrapFinalizePreflightInput is the Lesser-local request for Host finalize preflight/signing material.

type BootstrapFinalizePreflightResult added in v1.5.0

type BootstrapFinalizePreflightResult struct {
	Version                     string
	DigestHex                   string
	IssuedAt                    *time.Time
	ExpectedVersion             int
	NextVersion                 int
	SelfAttestationSigning      BootstrapFinalizeSigningInput
	BoundaryRequirementsJSON    string
	FinalizeRequestTemplateJSON string
	RegistrationPreviewJSON     string
	HostRequestID               string
}

BootstrapFinalizePreflightResult contains Host-owned finalize signing material. Lesser relays these fields unchanged; it never reconstructs the signing payload locally.

type BootstrapFinalizeResult added in v1.5.0

type BootstrapFinalizeResult struct {
	Version          string
	HostSoulAgentID  string
	PublishedVersion int
	PrincipalAddress string
	Publication      BootstrapPublicationEvidence
	Promotion        BootstrapPromotionEvidence
	HostRequestID    string
}

BootstrapFinalizeResult contains Host finalize/publication output needed for Lesser local soul binding and workflow projection.

type BootstrapFinalizeSigningInput added in v1.5.0

type BootstrapFinalizeSigningInput struct {
	SignerWallet    string
	SigningMethod   string
	MessageEncoding string
	MessageHex      string
	DigestHex       string
	CanonicalJSON   string
}

BootstrapFinalizeSigningInput contains the Host-owned self-attestation signing payload.

type BootstrapPrincipalPreflightInput added in v1.5.0

type BootstrapPrincipalPreflightInput struct {
	RegistrationID       string
	PrincipalAddress     string
	PrincipalDeclaration string
	DeclaredAt           time.Time
}

BootstrapPrincipalPreflightInput is the Lesser-local request for Host principal declaration preflight.

type BootstrapPrincipalPreflightResult added in v1.5.0

type BootstrapPrincipalPreflightResult struct {
	Version          string
	PrincipalAddress string
	SignerAddress    string
	SigningMethod    string
	MessageEncoding  string
	MessageHex       string
	DigestHex        string
	CanonicalJSON    string
	DeclaredAt       *time.Time
	HostRequestID    string
}

BootstrapPrincipalPreflightResult contains Host-owned signing material.

type BootstrapPrincipalVerifyInput added in v1.5.0

type BootstrapPrincipalVerifyInput struct {
	RegistrationID       string
	WalletSignature      string
	PrincipalAddress     string
	PrincipalDeclaration string
	PrincipalSignature   string
	DeclaredAt           time.Time
}

BootstrapPrincipalVerifyInput is the Lesser-local request for Host proof verification.

type BootstrapPrincipalVerifyResult added in v1.5.0

type BootstrapPrincipalVerifyResult struct {
	RegistrationID   string
	HostSoulAgentID  string
	WalletAddress    string
	PrincipalAddress string
	OperationID      string
	PromotionStage   string
	HostRequestID    string
}

BootstrapPrincipalVerifyResult contains Host verification output needed by the GraphQL state.

type BootstrapPromotionEvidence added in v1.5.0

type BootstrapPromotionEvidence struct {
	AgentID                  string
	RegistrationID           string
	Stage                    string
	RequestStatus            string
	ReviewStatus             string
	ReadinessStatus          string
	AnchorState              string
	LatestConversationID     string
	LatestConversationStatus string
	PublishedVersion         int
	GraduatedAt              *time.Time
}

BootstrapPromotionEvidence contains Host promotion continuity fields.

type BootstrapPublicationEvidence added in v1.5.0

type BootstrapPublicationEvidence struct {
	AgentID                    string
	PublishedVersion           int
	RegistrationURI            string
	RegistrationS3Key          string
	VersionedRegistrationURI   string
	VersionedRegistrationS3Key string
	AnchorState                string
	PublishedAt                *time.Time
}

BootstrapPublicationEvidence contains Host publication evidence for the versioned hosted/off-chain registration artifact.

type BootstrapWalletChallenge added in v1.5.0

type BootstrapWalletChallenge struct {
	ID        string
	Address   string
	ChainID   int
	Nonce     string
	Message   string
	IssuedAt  *time.Time
	ExpiresAt *time.Time
}

BootstrapWalletChallenge contains the Host-issued wallet signing message.

type HostBootstrapError added in v1.5.0

type HostBootstrapError struct {
	Code          string
	Message       string
	Source        string
	StatusCode    int
	HostRequestID string
	Err           error
}

HostBootstrapError describes a bounded, client-safe failure returned while talking to Host's instance-key bootstrap API.

func (*HostBootstrapError) Error added in v1.5.0

func (e *HostBootstrapError) Error() string

func (*HostBootstrapError) Unwrap added in v1.5.0

func (e *HostBootstrapError) Unwrap() error

type Service

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

Service resolves principal-bound souls for a Lesser instance and manages explicit incorporation bindings.

func NewService

func NewService(accountRepo accountRepository, instanceRepo instanceRepository, cfg *config.Config, logger *zap.Logger) *Service

NewService creates a new soul service.

func (*Service) BeginBootstrapRegistration added in v1.5.0

func (s *Service) BeginBootstrapRegistration(ctx context.Context, input BootstrapBeginInput) (*BootstrapBeginResult, error)

BeginBootstrapRegistration calls Host's instance-key registration begin route.

func (*Service) CompleteBootstrapConversation added in v1.5.0

CompleteBootstrapConversation completes a Host mint conversation and returns the Host-owned declaration output checkpoint.

func (*Service) FinalizeBootstrap added in v1.5.0

func (s *Service) FinalizeBootstrap(ctx context.Context, input BootstrapFinalizeInput) (*BootstrapFinalizeResult, error)

FinalizeBootstrap relays Host finalize and publication. Hosted/off-chain success does not require on-chain mint transaction fields.

func (*Service) Incorporate

func (s *Service) Incorporate(ctx context.Context, principalUsername string, targetAgentUsername string, agentID string) (*Soul, error)

Incorporate explicitly binds a soul to a local agent chosen by the authenticated principal.

func (*Service) ListMine

func (s *Service) ListMine(ctx context.Context, username string) ([]Soul, error)

ListMine returns the current user's discoverable souls for this instance.

func (*Service) PrepareBootstrapFinalize added in v1.5.0

PrepareBootstrapFinalize calls Host finalize preflight and fails closed on unsupported signing metadata.

func (*Service) PrepareBootstrapPrincipalDeclaration added in v1.5.0

func (s *Service) PrepareBootstrapPrincipalDeclaration(ctx context.Context, input BootstrapPrincipalPreflightInput) (*BootstrapPrincipalPreflightResult, error)

PrepareBootstrapPrincipalDeclaration calls Host's principal declaration preflight route and fails closed on unsupported signing metadata.

func (*Service) ResolveBoundAgent added in v1.1.41

func (s *Service) ResolveBoundAgent(ctx context.Context, agentUsername string) (*Soul, error)

ResolveBoundAgent returns the canonical bound soul identity for a local agent username. It returns (nil, nil) when the agent is not soul-bound.

func (*Service) SendBootstrapConversationMessage added in v1.5.0

func (s *Service) SendBootstrapConversationMessage(ctx context.Context, input BootstrapConversationMessageInput) (*BootstrapConversationMessageResult, error)

SendBootstrapConversationMessage relays one mint-conversation turn to Host's instance-key SSE route and consumes the terminal event so GraphQL receives a bounded same-origin mutation result.

func (*Service) VerifyBootstrapPrincipalDeclaration added in v1.5.0

func (s *Service) VerifyBootstrapPrincipalDeclaration(ctx context.Context, input BootstrapPrincipalVerifyInput) (*BootstrapPrincipalVerifyResult, error)

VerifyBootstrapPrincipalDeclaration calls Host's combined wallet/proof/ principal declaration verification route.

func (*Service) WithHTTPClient

func (s *Service) WithHTTPClient(client *http.Client) *Service

WithHTTPClient overrides the HTTP client used for lesser-host requests.

func (*Service) WithHostInstanceKeyResolver added in v1.5.0

func (s *Service) WithHostInstanceKeyResolver(resolver func(context.Context, *config.Config, string) (string, error)) *Service

WithHostInstanceKeyResolver overrides instance-key resolution for tests.

type Soul

type Soul struct {
	AgentID                string
	Domain                 string
	LocalID                string
	ENSName                *string
	Wallet                 string
	TokenID                string
	MetaURI                string
	Avatar                 *SoulAvatar
	PrincipalAddress       string
	PrincipalSignature     string
	PrincipalDeclaration   string
	PrincipalDeclaredAt    string
	Status                 string
	LifecycleStatus        string
	LifecycleReason        string
	SuccessorAgentID       string
	PredecessorAgentID     string
	SelfDescriptionVersion *int
	Capabilities           []string
	MintTxHash             string
	MintedAt               *time.Time
	UpdatedAt              *time.Time
	Bound                  bool
	BoundAgentUsername     string
	BoundPrincipalAddress  string
	BoundAt                time.Time
	BoundUpdatedAt         time.Time
}

Soul represents a host-discovered soul plus local binding state.

type SoulAvatar added in v1.2.14

type SoulAvatar struct {
	TokenURI               string
	Image                  string
	CurrentStyleID         *int
	CurrentStyleName       string
	CurrentRendererAddress string
	Styles                 []SoulAvatarStyle
}

SoulAvatar represents the current soul avatar plus all configured style variants.

type SoulAvatarStyle added in v1.2.14

type SoulAvatarStyle struct {
	StyleID         int
	StyleName       string
	RendererAddress string
	Image           string
	Selected        bool
}

SoulAvatarStyle represents one renderer-backed avatar style option.

Jump to

Keyboard shortcuts

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